klaviyo-cli

A command-line interface for Klaviyo: campaigns, segments, flows, metrics, and scheduling. Built for humans and AI agents.

uvx --from klaviyo-cli klaviyo --help

No install needed. Or install it: pipx install klaviyo-cli or uv tool install klaviyo-cli. Requires Python 3.11+.

Built and maintained by BS&Co, a retention marketing agency for eCommerce brands. Read why we built it and how we made it safe to hand to AI agents: https://bsandco.us/blog-post/klaviyo-cli

Unofficial. Not affiliated with, endorsed, or supported by Klaviyo, Inc.

Quickstart

export KLAVIYO_API_KEY=pk_...

Get a private API key from Klaviyo under Settings > API Keys. Read commands need read scopes; commands that change data (patch, schedule, create, upload) need write scopes.

klaviyo list-campaigns --days 30
klaviyo account-health

Using with Claude Code and AI agents

--json is a global flag: put it before the command name for machine-readable output on any command:

klaviyo --json list-campaigns --days 30

Deletes are gated. The raw api passthrough can only delete templates (transport.py, DELETE_ALLOWED_PATHS). Segments, lists, campaigns, and flows can only be deleted with klaviyo delete <type> <id>, which prints what it is about to remove (profile count, status, and for segments and lists every flow and draft/scheduled campaign still using it), then requires the ID typed back, or --confirm <id> in a non-interactive shell. Without that confirmation nothing is deleted. Profiles cannot be deleted through this tool. Two commands can stop mail going to real people, and both require an explicit --yes flag or an interactive confirmation before they run: suppress (reversible — unsuppress undoes it) and unsubscribe (it revokes consent, which unsuppress cannot undo; reversing it takes a deliberate call to Klaviyo's bulk subscribe endpoint asserting fresh consent, which this CLI intentionally does not wrap).

Drop this in your repo's CLAUDE.md so an agent knows the tool exists:

## Klaviyo
Use the `klaviyo` CLI for Klaviyo data and actions (campaigns, segments,
flows, metrics). Auth via KLAVIYO_API_KEY env var. Pass --json before the
command for machine-readable output (e.g. `klaviyo --json list-campaigns`).
Run `klaviyo --help` for the full command list.

Command reference

Run klaviyo COMMAND --help for full options on any command.

Campaigns

Uses API revision 2026-10-15, where a campaign is a container of messages and the subject, sender and template live on each message's content variation. The ID a campaign shows in the Klaviyo UI (and in reporting) is its message ID, so that's the ID every command prints and takes. A container campaign ID also works when the container holds one message. A draft's planned send date has no field at 2026-10-15, so patch-campaign --date, upload-sms and schedule (and the planned date get-campaign shows) use revision 2026-07-15.

Segments

Flows

Delays are always live, so adding, changing, or removing one in a live flow affects profiles already in it; those commands refuse a live flow without --live-ok. Klaviyo can't insert conditional/trigger splits or A/B tests, and trigger and profile filters can't be edited through the API at all. Inserts aren't idempotent, so each command reads the flow back instead of retrying.

Profiles

Events

Metrics

Forms

Uses Forms API revision 2026-10-15 (needs forms:read, plus forms:write to edit). The API only edits draft versions: live versions are echoed back unchanged, versions can't be added to or removed from an existing form, and every edit stays in draft until published. Forms with no display triggers have to be handled in the form editor.

A/B tests: ab-test-form <form_id> --name NAME [--variant A --variant B] creates a new draft form with one A/B variation per --variant, each a copy of the source's live version; edit each with form-replace ... --version <id>. Klaviyo adds one extra non-test version named after the form. The API can't publish a form with a draft A/B test (Klaviyo's rule), so start the test in the form editor. Read results with form-performance --form <id> --by-version. copy-form on a variation makes a plain form from it (e.g. to keep the winner).

Quirks worth knowing before you edit a real form:

• Every save must send the live version back exactly as returned, and Klaviyo often rejects it anyway: editor-built forms carry things its own validator refuses (empty layout rows, URL rules with no URLs, two teasers on one device type), and publishing from the editor does not clean them up. When that happens: unpublish-form, save the draft (now the only version), publish-form. Same form ID; the form is off the site for a few seconds; if the save fails, republish the untouched draft to restore it.
• unpublish-form deletes the live version rather than pausing it. To pause a form, toggle it off in the Klaviyo UI.
• Every publish creates a new live version ID (the editor does the same).
• Drafts are cleaned automatically before saving (empty rows, empty URL rules); copy-form also drops a second same-device teaser and says so.
• Survey/checkbox options have a label and a value; the value is what lands on the profile, so change both.
• Delete a form with klaviyo delete form <id>.

Editing emails

edit-template changes copy, links, or images in an existing email: a template ID, --campaign <id>, or --flow <id> --email N (numbered as in flow-detail). With no edits it lists the email's copy and numbered images.

klaviyo edit-template --campaign <id> --replace "Ends Friday" "Ends Sunday"
klaviyo edit-template --flow TCAqyz --email 2 --image 3 ./new-hero.png --alt 3 "New hero"
klaviyo edit-template <template_id> --replace "utm_campaign=old" "utm_campaign=new" --dry-run

• Works on drag-and-drop and HTML templates. --replace changes every match, including button, image, and header links in drag-and-drop emails. Text split by formatting (half bold) won't match; use a shorter piece. If any --replace finds nothing, nothing is saved.
• New images (URL or local JPEG/PNG/GIF up to 5 MB) are imported into the account's image library first, because Klaviyo requires a library asset on every drag-and-drop image. Local files go up as JSON, so this works through JSON-only proxies.
• Klaviyo's API drops crop settings on any drag-and-drop save: a cropped image still shows cropped, but the crop can't be re-adjusted in the editor.
• Templates copied from another Klaviyo account reference that account's images, which Klaviyo rejects on save. Those images are re-imported (hidden) into this account and the save is retried.
• Klaviyo's API can't open some drag-and-drop templates (a header block with a logo in the "links" layout). Edit those in the Klaviyo editor.
• A sent campaign is refused. Scheduled campaigns and live flows are edited with a note that the change goes out on the next send.

convert-template <id> turns an HTML template into a new drag-and-drop one (the original is untouched); convert-template --campaign <id> does it for a draft campaign and puts the drag-and-drop version on the campaign. Paid Klaviyo plans only, one conversion a minute, 1-2 minutes each. Text, links, and images carry over; the hidden preheader div doesn't (use the campaign's preview text). Check the result in the editor before sending.

Billing

Needs the usage:read scope ("Usage: Read Access" on the API key). Keys made before Klaviyo added that scope don't have it, even full-access ones. The API can only read usage; there is no endpoint that changes a plan.

SMS

Images

Delete

Raw API

That's 50 commands total.

Multi-account profiles

For managing more than one Klaviyo account, put credentials in ~/.config/klaviyo-cli/config.toml:

default_profile = "acme"

[profiles.acme]
api_key = "pk_acme_..."

[profiles.other-brand]
api_key = "pk_other_..."

Select a profile with --profile (or -p), or set KLAVIYO_PROFILE:

klaviyo --profile other-brand account-health
KLAVIYO_PROFILE=other-brand klaviyo account-health

Precedence: an explicit --profile (or KLAVIYO_PROFILE) wins first. Otherwise KLAVIYO_API_KEY is used if set. Otherwise the CLI falls back to default_profile in the config file.

Agencies running the CLI across many clients can go further and embed it: re-expose every command under a host CLI with per-client auth resolution, so yourcli campaign-performance acme --days 30 resolves credentials for acme before the call. See the wrap_with_account and build_host_group docstrings in src/klaviyo_cli/embed.py.

License

MIT. See LICENSE.

Built and maintained by BS&Co, a retention marketing agency for eCommerce brands.