We Published a Free Klaviyo CLI (Built for Humans and AI Agents)

We published klaviyo-cli, a free, open-source command line interface for Klaviyo. It covers campaigns, segments, flows, profiles, events, and metrics in 32 commands, and it's designed from the ground up to be safe to hand to an AI agent. You can try it without installing anything:

uvx --from klaviyo-cli klaviyo --help

It's on PyPI, MIT licensed, with the source on GitHub. It's unofficial: not affiliated with, endorsed, or supported by Klaviyo, Inc.

Why We Built It

We run Klaviyo for 12 client accounts, and running that many accounts means a lot of repetition: pulling the same reports, building the same audiences, checking the same things, over and over, in a dashboard that only shows you one account at a time. Reporting was the biggest pain. Answering a simple question like "how is flow revenue trending" meant logging in, clicking through reports, and exporting CSVs, per account, every time.

The CLI collapsed that. We use it almost daily now: scheduling emails, pulling reports, creating audiences, spot-checking accounts. A segment build that used to take 10 to 15 minutes in the UI, plus the double-check afterward to make sure the logic was right, now takes about 20 seconds. And cross-account work got dramatically simpler. Recreating an audience from one account in another used to mean opening both dashboards and following an SOP. Now it's one instruction: read how the segment is built over there, create the same thing over here.

The second reason is the bigger one: we wanted our AI agents to do real Klaviyo work. We've written before about using agents to bulk-suppress a 1,600-contact do-not-solicit list and to write campaign copy against real account data. A command line tool is the natural interface for that kind of work: agents already know how to run shell commands, chain them, and parse JSON. No custom integration required.

Why not an MCP server? We tried that route first, and in our experience MCP servers tend to dump piles of raw data into the context that you then have to sort through. A CLI gave us tighter control over what each command returns, made repetitive operations one-liners, and is much easier to extend when we need a new command. Your mileage may vary; this is just what worked for us.

What It Does

32 commands across campaigns, segments, flows, profiles, events, metrics, and SMS, plus a raw API passthrough for anything not covered. A few examples of what a single command gets you:

# Everything sent in the last 30 days
klaviyo list-campaigns --days 30

# Profiles count, lists, and metrics in one shot
klaviyo account-health

# Flow revenue trended by week
klaviyo flow-series FLOW_ID --interval weekly

# Dump a campaign's subject line + body copy (--html for full HTML)
klaviyo get-creative CAMPAIGN_ID

# Every segment with its profile count
klaviyo segment-sizes

# Raw API access for anything else
klaviyo api GET /api/lists

The flow reporting commands exist because trended per-flow revenue is one of the metrics Klaviyo doesn't give you in a single view. flow-series answers "is my welcome flow getting better or worse" in one command instead of a spreadsheet project.

It writes, too. You can create flows and segments in draft (with duplicate guards), patch campaign send times and audiences, upload SMS campaign drafts, push custom events to profiles, and manage suppressions in bulk. That last one powers workflows like the automatic reactivation flow for suppressed profiles we wrote about recently.

The Interesting Part: Making It Safe for AI Agents

Handing an AI agent a live API key to your email list is a reasonable thing to be nervous about. Your subscriber data and send history are not recoverable if something deletes them. So instead of trusting the agent to be careful, we made the dangerous operations unreachable at the tool level:

• Deletes are blocked in the transport layer. 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.
• The one command that stops mail requires confirmation. suppress deletes nothing, but because it halts sends to real people it won't run without an explicit --yes flag or an interactive yes.
• Unsuppress never resubscribes anyone. It only removes manual suppressions, so it can't be used to mail people who opted out.

The result: an agent with this tool can read anything and change campaign content, timing, and audiences, but it cannot delete subscriber data, segments, or send history. The guardrails live in the tool, not in the prompt, which means they hold even when the agent does something you didn't anticipate.

To wire it into Claude Code or any agent that reads a CLAUDE.md, drop this in your repo:

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

Multi-Account Support for Agencies

If you manage more than one Klaviyo account, you can put credentials in a config file and switch with a flag:

# ~/.config/klaviyo-cli/config.toml
default_profile = "acme"

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

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

klaviyo --profile other-brand account-health

Agencies running it across many clients can go further and embed the whole command set inside their own internal CLI with per-client auth resolution. The repo documents how in embed.py. That's exactly how we run it internally: one command, any client, right credentials resolved automatically.

Installing It

# No install (uv)
uvx --from klaviyo-cli klaviyo --help

# Or install it
pipx install klaviyo-cli
uv tool install klaviyo-cli

Requires Python 3.11+. Auth is a Klaviyo private API key (Settings → API Keys) in the KLAVIYO_API_KEY env var. Read commands need read scopes; commands that change data need write scopes, so you can hand out a read-only key if that's all you need.

The full command reference is in the README, and issues and PRs are welcome. And if you'd rather have an agency that builds tooling like this running your email program, talk to us.