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

Segments

Flows

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>.

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.