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

SMS

Images

Delete

Raw API

That's 43 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.