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

Destructive Klaviyo operations are blocked at the CLI level. Klaviyo's DELETE endpoints for profiles, lists, segments, campaigns, and flows are not reachable through this tool, even via the raw api passthrough. Only template deletion is allowlisted (transport.py, DELETE_ALLOWED_PATHS). This is why it's safe to hand klaviyo-cli to an agent with a live API key: the agent can read anything and change campaign content, timing, and audiences, but it cannot delete subscriber data, segments, or send history. 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

Raw API

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