Klaviyo CLI

Before you begin

The Headless Klaviyo command line interface offers a way to manage Klaviyo campaigns, flows, segments, and universal content blocks as files via the command line.

You can also find installation instructions and basic usage information in the Headless Klaviyo CLI readme.

Install Klaviyo CLI

Install pipx if it is not already available. For assistance, review the pipx installation guide.

Use pipx to install the Klaviyo CLI.

pipx install headless-klaviyo

Test that the klaviyo command can now be used.

klaviyo --help

Update Klaviyo CLI

To update your Klaviyo CLI install to the latest version:

pipx upgrade headless-klaviyo

Set environment variables

The Headless Klaviyo CLI tool requires a private API key to authenticate requests, which can be passed in using the --api-key option. We recommend setting your private key as the environment variable KLAVIYO_API_KEY. Your private API key must have appropriate read and write access to use all CLI functions. See how to create a private API key for more information.

Local files are saved to named subfolders within your current working directory unless otherwise specified. For example, if you run a command from the resources directory, segment resources will save to the resources/segments subfolder, flows to resources/flows and so forth.

You can set the following environment variables to specify a directory that will always be used for that resource type.

• KLAVIYO_BLOCK_PATH
  Path to the directory used for saving universal content block files.
• KLAVIYO_CAMPAIGN_PATH
  Path to the directory used for saving campaign files.
• KLAVIYO_FLOW_PATH
  Path to the directory used for saving flow files.
• KLAVIYO_SEGMENT_PATH
  Path to the directory used for saving segment files.
• KLAVIYO_REPORTS_PATH
  Path to the directory used for saving reporting files.

CLI commands

The CLI is invoked by entering klaviyo followed by a subcommand name and the relevant options for that subcommand.

All subcommands support the following flags. Review the subcommand sections below for additional flags supported by each.

• --help
  If you aren't sure what options and arguments to specify for a subcommand, use the --help flag for that command. For example, to see the available options for the get campaigns subcommand, use:

klaviyo get campaigns --help

• --verbose, -v
  Enables verbose output.
• --api-key
  The private API key used to authenticate your requests. Can also be set as an environment variable.

The resource definition files stored by these commands generally match the format of the data section of the json:api payload used for interacting with the Klaviyo API. For specifics on the formats of these resource definitions, refer to the Klaviyo API documentation. For example, the campaign data model is described in the Campaigns API overview.

📘

The resource definition files created through this CLI exclude information that changes every time the API is called, such as the screenshot URL for universal content blocks and the updated date for all resource types.

Get

The get command retrieves resource definitions from Klaviyo and stores them as local files.

Supported subcommands:

• all
• block, blocks
• campaign, campaigns
• flow, flows
• segment, segments

Additional supported flags:

• --stdout
  Outputs the result to standard output instead of a file and suppresses all other output.
• --overwrite-mode
  Supports the following modes: overwrite, interactive, keep-local.
• --resource-path
  Directory to use for the relevant resource. For example, to define the directory for a segment, use --segment-path.

To retrieve a specific resource, provide its resource ID. For example, to get a segment with the ID R6qs5F:

klaviyo get segment R6qs5F

Request results are saved to a directory set in the PATH environment variable for that resource, or the default location in the current working directory if not specified. To specify a "new-segments" directory as the save location for the segment above, use:

klaviyo get segment R6qs5F --segment-path resources/new-segments

To retrieve all resources of a type, use the plural version of the subcommand. These commands support all options that the singular versions do and do not require a specified resource ID.

klaviyo get segments

To retrieve all supported resource types in an account, use the all subcommand.

klaviyo get all

By default, you will be prompted to confirm that you would like to overwrite an existing file if one exists. You can change this behavior with the --overwrite-mode flag.

For example, the following command retrieves the segment to the file resources/segments/segment-R6qs5F.json and overwrites that file if it already exists, without asking for confirmation.

klaviyo get segment R6qs5F --overwrite-mode overwrite --segment-path resources/segments

Use the --stdout flag to indicate that the get command should print the retrieved definition to STDOUT and suppress all other output.

klaviyo get segment R6qs5F --stdout

Inspect

The inspect command outputs a table with information about a resource based on a local resource definition file.

Supported subcommands:

• block
• campaign
• flow
• segment

Additional supported flags:

• --resource-path
  Directory to use for the relevant resource. For example, to define the directory for a block, use --block-path.
• --resource-id
  ID of the relevant resource. For example, to define the ID of a campaign, use --campaign-id.
• --resource-file
  Path to the relevant resource. For example, to define the path to a flow, use --flow-file.

When making this request, specify a file to inspect with the relevant file path or ID flags. For example, the following are equivalent ways to inspect a specific flow definition:

klaviyo inspect flow --flow-id QWEbek

klaviyo inspect flow --flow-file flow-QWEbek.json

If neither of these options is specified, the command will pull in a definition stored from STDIN.

The inspect table lists the resource's attributes and their corresponding values, including the ID, name, created timestamp in UTC, and the definition in json.

Generate

The generate command creates a local resource definition file for a new resource.

Supported subcommands:

• block
• campaign

Additional supported flags:

• --audience
  The audience used for a campaign. This can be a specified list and/or segment ID, an array of list and/or segments IDs, or an object with "include" and "exclude" lists.
• --block-path
  Directory to use for the block.
• --block-type
  The block type for the content block, either text or html.
• --campaign-path
  Directory to use for the campaign.
• --display
  Sets which devices the universal content block will be visible on, desktop, mobile, or all
• --email-label
  An optional label for a campaign email.
• --email-subject
  The subject line used for a campaign email.
• --message-channel
  The message channel used for sending a campaign, either email or sms.
• --name
  The name of the campaign or block.
• --send-strategy
  The sending strategy used for an email or sms campaign. Can be immediate, static, throttled, or smart send time.
• --sms-body
  The body text of the sms campaign message.
• --tracking
  Optionally include UTM tracking.

When generating a new resource with this command, the CLI will interactively prompt you to complete any necessary parameters for the resource before saving the local file. When prompted, make selections using the arrow keys. Your cursor is indicated by a caret > and colored text.

• Up and down arrows move your cursor through groups.
• Right arrow key once to select one group.
• Right arrow key twice to select all groups.
• Left arrow key once to deselect one group.
• Left arrow key twice to deselect all groups.

Hit the Enter key to save your selection(s).

Type a filter term to view a subset of all groups. When using a filter, select all and deselect all will only apply to groups that fit the filter criteria.

To generate a new local definition file for a block using only prompts:

klaviyo generate block

To generate a new local definition file for a universal content text block with the name "Test UC Block" that displays on both desktop and mobile devices:

klaviyo generate block --name "Test UC Block" --block-type text --display all

Once a resource definition file is created with the generate command, it can be modified further with the text editor of your choice.

Create

The create command creates a new Klaviyo resource based on a local definition file.

Supported subcommands:

• block
• campaign
• flow
• segment

Additional supported flags:

• --resource-path
  Directory to use for the relevant resource. For example, to define the directory for a block, use --block-path.
• --resource-file
  Path to the relevant resource. For example, to define the path to a flow, use --flow-file.

Specify a local file to use for resource creation with the resource-appropriate flag. For example, to create a segment based on a definition file named new_segment_1.json:

klaviyo create segment --segment-file new_segment_1.json

After creating the resource, the result will be saved to a new local file with its assigned ID in the resource path. For example, the create call above may create a file named segment-HEvmTJ.json where HEvmTJ is its assigned segment ID in Klaviyo. This file can be opened in a text editor or you can view its attributes using the Inspect subcommand.

Update

The update command updates an existing Klaviyo resource to match a local resource definition.

Supported subcommands:

• block
• campaign
• flow
  The flow resource currently has limited support. Only the status attribute for existing flows can be updated via CLI.
• segment

Additional supported flags:

• --resource-path
  Directory to use for the relevant resource. For example, to define the directory for a block, use --block-path.
• --resource-id
  ID of the relevant resource. For example, to define the ID of a campaign, use --campaign-id.
• --resource-file
  Path to the relevant resource. For example, to define the path to a flow, use --flow-file.

For example, if you have modified the definition of a campaign locally and want to push the updated definition to its corresponding resource in Klaviyo without creating a new campaign resource:

klaviyo update campaign --campaign-file campaign-01G5M1HWYX67DRW8AZEPWZAK9B.json

Delete

The delete command deletes a Klaviyo resource with the provided resource ID. Local files are not modified or deleted.

Supported subcommands:

• block
• campaign
• flow
• segment

For example, to delete the segment with ID R6qs5F use:

klaviyo delete segment R6qs5F

🚧

Deleting a resource is a destructive change that cannot be undone. You will be prompted with a warning before the resource is deleted. Use caution when deleting resources from Klaviyo. We recommend using a Get command to save a local copy of any resources prior to deleting it. Please keep in mind that creating a new resource from the local definition will result in a new resource ID.

Report

The report command creates a report about a Klaviyo resource, saved as a CSV file. We recommend reviewing the Reporting API Overview for more information on series and values report types, report timeframes, and report statistics.

Supported subcommands:

• campaign
• flow
• form
• segment

Supported additional flags:

• --conversion-metric ID
  The conversion metric used to calculation conversion statistics. Include the metric ID, e.g., --conversion-metric RESQ6t.
• --interval
  For series reports only, select the report interval. Interval types include: hourly, daily, weekly, monthly.
• --report-path
  Directory to use for storing the report.
• --report-statistics
  The statistics to report on, depending on resource type. Accepts an individual statistic, an array of statistics, or all. See available statistics.
• --report-type
  The type of report, either series or values.
• --timeframe
  The timeframe for the report. See available timeframes.

When generating a report with this command, the CLI will interactively prompt you to complete any necessary parameters for the resource before saving the local file. When prompted, make selections using the arrow keys. Your cursor is indicated by a caret > and colored text.

• Up and down arrows move your cursor through groups.
• Right arrow key once to select one group.
• Right arrow key twice to select all groups.
• Left arrow key once to deselect one group.
• Left arrow key twice to deselect all groups.

Hit the Enter key to save your selection(s).

Type a filter term to view a subset of all groups. When using a filter, select all and deselect all will only apply to groups that fit the filter criteria.

For example, the following command will create a report about a campaign with ID 01G5M1HWYX67DRW8AZEPWZAK9B over the last 12 months, and will prompt you to select the statistics for the report, as well as the metric used to calculate conversion statistics.

klaviyo report campaign 01G5M1HWYX67DRW8AZEPWZAK9B --timeframe last_12_months

Combine CLI commands

The Klaviyo CLI supports the pipe | operator to combine two or more commands into a single request.

Inspect a remote resource

To view the details of a remote resource without saving it as a local definition file first, use the standard output flag to store the results of a get command, then pipe it into a subsequent inspect command.

For example, to inspect a specific, remote segment from Klaviyo:

klaviyo get segment R6qs5F --stdout | klaviyo inspect segment

Compare remote resource to local

The diff command compares the definitions of two resources line by line and displays the differences. Store the output of a get command with the standard output flag, then pipe it into a diff command to compare a remote resource to a local resource with a single request.

For example, to compare a remote flow with the local definition file:

klaviyo get flow UNvDnz --stdout | diff - flows/flows-UNvDnz.json

Create a copy of a resource

If you would like to create a new resource with the same definition as an existing resource, it is recommended that you rename the copied file, and required that you remove the id of the original resource from that file.

📘

Check out the Get section if you are just getting started or do not have any local definitions saved.

Use the concatenate cat command combined with the stream editor sed command to modify the definition file's contents, then make a klaviyo create command to create the new resource from it.

For example, strip the id value within a saved campaign definition file, then use the file to create a new campaign:

cat campaigns/campaign-01G5M1HWYX67DRW8AZEPWZAK9B.json | sed '/"id": /d' | klaviyo create campaign

Example use cases

Create a campaign

To create a new campaign with the Klaviyo CLI, we must first generate a local definition file before creating a Klaviyo resource from that definition. In this example, we'll create a new Cyber Monday campaign. These example commands presume you have the KLAVIYO_API_KEY environment variable set up using a private API key from your primary Klaviyo account.

Generate a local campaign definition

1. Generate a local definition file for a campaign with a given name. The CLI will then prompt you for additional parameters.

Your command will look something like this:

klaviyo generate campaign --name "Cyber Monday Campaign"

2. The CLI will retrieve all segments and lists from your account that are available to be used in this campaign. Choose which groups you'd like to include in the campaign audience using the arrow keys and filters. When the desired groups have been selected, hit Enter to save your selections.
3. Next, you will be prompted to select groups to exclude from this campaign. Select one or more groups to exclude and hit Enter.
4. Choose a send strategy by moving your cursor to one of the following options, then save your selection:
   • Immediate
   • Static
   • Throttled
   • Smart send time

📘

For more information about which campaign send strategy suits your needs, check out our guide to understanding campaign schedule and send options.

5. Use your arrow keys to set a send time for your campaign. Depending on the send strategy you use, you may be prompted for additional parameters.
6. Select the message channel to be used, either email or sms.
7. Optionally include UTM tracking parameters. You can choose to set custom UTM parameters or the default for your account.
8. Include a label if desired. To skip, hit Enter.
9. If you are sending an email campaign, enter a subject line for the email message, then optionally enter preview text. When sending an SMS campaign, enter the body text for the SMS message. Hit Enter to complete the local file generation.

The CLI will display the file location for the newly generated campaign definition. You can now edit this file locally with a text editor to further customize your campaign.

Create a Klaviyo resource from a local definition

Now that we have a local definition file and are satisfied with its parameters, we can use this definition to make campaigns in Klaviyo.

1. Create a Klaviyo resource from the specified definition file by passing in the --campaign-file command and the path to the file.

Your command may look like:

klaviyo create campaign --campaign-file new_campaign_1.json

2. When your request has been processed, you'll see a success message on creation or an error if your resource could not be created. The campaign will be saved to a new file with its assigned ID in the specified resource path. Note that the definition file used to create a resource must not already have an ID. If no file option is specified, the command will read from STDIN.

Your campaign can now be viewed in your Klaviyo account! Don't forget to set your campaign status to Live.

Update a segment across multiple accounts

If you work with multiple Klaviyo accounts, you can use the Update command to simplify the process of updating multiple segments that should have the same definition. For example, you can make changes to a "VIP Customers" segment in a local file, and update the "VIP Customers" segment across all of your accounts.

These example commands presume you have the KLAVIYO_API_KEY environment variable set up using a private API key from your primary Klaviyo account.

Get segment definition

Begin by retrieving the segment definition(s) from your primary Klaviyo account. To modify just the "VIP Customers" segments, for example, we can pass in a specific segment ID to store its definition to a local file.

The call to retrieve one segment's definition may look like:

klaviyo get segment HEvmTJ

This command will save the segment definition to a subfolder of the working directory named segments. For example, your file may be named segment-HEvmTJ.json. If you have already saved this segment definition and wish to overwrite your local file's definition with any modifications made in Klaviyo, use the --overwrite-mode flag and the interactive option to be prompted for confirmation.

klaviyo get segment HEvmTJ --overwrite-mode interactive

Modify segment definition

Open the segment definition in a text editor and modify its attributes as desired. When you are finished, save the changes.

If the segments across your other Klaviyo accounts do not already have locally stored definition files, duplicate the modified segment definition file depending on the number of Klaviyo accounts you use. Then, update the id value in each file to match the segment IDs of your "VIP Customers" segments from each of your Klaviyo accounts.

If you have already created local files for the "VIP Customers" segments across your accounts, copy and paste the updated definition json, beginning at attributes. Do not overwrite the segment IDs.

Update all segment definitions

Update segments with the definition of the given segment file. When updating resources from multiple Klaviyo accounts, you will need to pass in that account's private API key as the command --api-key. Ensure that the segment ID you are updating matches the account whose private API key you are using.

klaviyo update segment --segment-file segment-HEvmTJ.json --api-key pk_...

Repeat this command with each segment definition file and private API key for your Klaviyo accounts.

Add a flow to a new account

If you have a flow in an existing Klaviyo account that you would like to add to a new Klaviyo account, you can retrieve the flow's definition and subsequently create a new flow resource with the same definition in your new account. These example commands presume you have the KLAVIYO_API_KEY environment variable set up using a private API key from your primary Klaviyo account.

Get the flow definition

Begin by retrieving the existing flow's definition from your Klaviyo account using its flow ID.

The call to retrieve one flow's definition may look like:

klaviyo get flow UNvDnz

This command will save the flow definition to a subfolder of the working directory (named flows by default). For example, your file may be named flow-UNvDnz.json.

Duplicate this json file. To avoid confusion, we recommend renaming it as a definition file, such as flow-definition-new.json.

Modify the flow definition

Open the definition file in a text editor.

For each action in the attributes.definition.actions array, copy the value of the id field and update the temporary_id from null to the copied value. Then, delete the id field and its corresponding value.

Update the trigger ID depending on the type of flow trigger:

If you are using a metric-triggered flow, log in to the new account and copy the metric ID of the flow trigger, or retrieve the metric via API. When working with custom metrics, you can get metric IDs of custom metrics.

If you are using a list or segment-triggered flow, retrieve the list or segment IDs from within the new account or using the Lists API and Segments API. Don't forget to create the list or segment in the new account if it does not already exist!

In the triggers array, update the id field to the metric, list, or segment ID from the new account.

🚧

Flow actions may have multiple unique IDs. Each unique ID associated with the source Klaviyo account must be updated with the corresponding ID from the new account. For example, if your flow includes an email, you must delete the message ID value and delete or replace template ID.

Next, delete the flow ID from the top of the file. This ID references the flow resource in your primary account. When we run the create command to add the new flow from this definition, it is automatically assigned a new flow ID associated with your new Klaviyo account.

Finally, set any live messages in the flow definition to draft.

📘

Your flow definition can be modified further in your text editor, however, please keep in mind that only the status attribute can receive updates via the Update command, should you choose to push those updates to your primary Klaviyo account.

Create a new flow resource

Create a Klaviyo resource from the specified definition file by passing in the --flow-file flag and the path to the file. Be sure to use the private API key of the new account when making your request.

Your command may look like:

klaviyo create flow --flow-path resources/flows --flow-file flow-definition-new.json --api-key pk_...

The flow will be saved to a new file with its assigned ID in the specified resource path.

To learn more about working with flows in Klaviyo, check out our library of flow resources on the Klaviyo Help Center.

Additional resources

• Universal Content API
• Campaigns API
• Flows API
• Segments API
• Reporting API