kreel CLI reference

kreel is Kreel’s command line tool. It calls the same agent-facing REST API that mirrors Kreel’s MCP tools, so a summary or a Query DSL result from kreel matches what an agent gets over MCP. It’s meant for scripts, CI jobs, and terminal use, not for chatting with an AI assistant.

Connecting an AI assistant?

If you want Claude, ChatGPT, or another assistant to query your Kreel data directly, connect over MCP instead. The CLI is for running commands yourself or from a script.

Install

Today, kreel installs from a checkout of the Kreel source repository. Requires Python 3.10 or newer.

cd cli
python -m pip install -e .

This installs the kreel command (package kreel-cli).

Authenticate

You need an API key first. See API keys to create one from the API keys page in the left navigation. Keys start with kreel_live_.

1. Run kreel auth login.
2. Paste your API key when prompted. The input is hidden.
3. Run kreel auth status to confirm you’re authenticated.

kreel auth login
# API key: (hidden input)

kreel auth login also accepts --server to point at a non-default server URL, stored alongside the key.

To check your current login:

kreel auth status
# Authenticated  key=kreel_live_8f3e12...  server=https://api.kreel.ai

To remove the stored key:

kreel auth logout

kreel auth login rejects a key that doesn’t start with kreel_live_ and exits with an error. Credentials are stored in ~/.kreel/config.toml.

Choose a brand

Most API keys can reach more than one brand in a workspace, so commands need to know which one to query. Find your brand’s ID with:

kreel brands

Then pass it with the global --brand (or -b) flag, which must come before the subcommand:

kreel --brand <brand-id> summary --period 30d

If you don’t want to pass --brand every time, set the KREEL_BRAND environment variable instead.

export KREEL_BRAND=<brand-id>
kreel summary --period 30d

Precedence: --brand on the command line overrides KREEL_BRAND, which overrides a default_brand stored in ~/.kreel/config.toml. If none of those are set, requests go out with no brand at all - that only works if your API key is bound to a single brand. For a key that reaches multiple brands, most commands fail without one of these set.

Output format

The global --format flag accepts compact (default) or json. compact is formatted for reading in a terminal. json returns the raw API response, useful for scripting.

kreel --brand <brand-id> --format json summary --period 30d

Some commands always return JSON

kreel query, kreel creatives, kreel context, kreel brands, and kreel publish always print JSON, regardless of --format. These mirror the exact response shape an agent gets from the equivalent MCP tool, so their output isn’t reformatted.

Commands

| Command | Description | |---|---| | kreel auth login | Store an API key locally so later commands are authenticated. | | kreel auth status | Show which key and server the CLI is currently using. | | kreel auth logout | Remove the stored API key. | | kreel brands | List the brands your API key can reach. | | kreel summary | Cross-platform revenue, spend, and order summary for a period. | | kreel compare | Compare a metric across platforms. | | kreel anomalies | Flag metrics whose recent average deviates from the prior 14-day baseline by more than a threshold. | | kreel meta campaigns | Meta Ads campaign performance. | | kreel google campaigns | Google Ads campaign performance. | | kreel klaviyo performance | Klaviyo campaign or flow performance. | | kreel shopify cohorts | Customer cohort retention from Shopify orders. | | kreel query | Run an allowlisted Query DSL expression. | | kreel creatives | Ad creatives with performance, tags, and fatigue signals. | | kreel context | Operational metadata and the Brand Knowledge Base for the active brand. | | kreel publish | Publish a local HTML file as a hosted report. | | kreel --version (or -v) | Print the installed CLI version. |

Examples

# Cross-platform summary for the last 30 days
kreel --brand <brand-id> summary --period 30d

# Compare ROAS between Meta and Google over 30 days
kreel --brand <brand-id> compare --platforms meta,google --metric roas --period 30d

# Flag any metric that moved more than 20% vs its 14-day baseline, last 7 days
kreel --brand <brand-id> anomalies --period 7d --threshold 20

# Top Meta campaigns by spend, last 7 days
kreel --brand <brand-id> meta campaigns --sort spend --limit 10 --period 7d

# Top Google campaigns by ROAS, last 7 days
kreel --brand <brand-id> google campaigns --sort roas --limit 10 --period 7d

# Klaviyo flow performance, last 30 days
kreel --brand <brand-id> klaviyo performance --source-type flow --sort revenue --period 30d

# Six-month Shopify customer cohort retention
kreel --brand <brand-id> shopify cohorts --months 6

# Run a Query DSL expression (same DSL as the MCP `query` tool and the REST API)
kreel --brand <brand-id> query '{"from": "daily_channel_summary", "select": ["date", "channel", "spend", "revenue", "roas"], "where": {"date": {"gte": "2026-06-01"}}, "order_by": [{"field": "date", "dir": "desc"}], "limit": 30}'

# Meta creatives with tags, for a date range
kreel --brand <brand-id> creatives --platform meta --fields tags --date-range '{"start": "2026-06-01", "end": "2026-06-30"}' --limit 50

# Operational metadata and Brand Knowledge Base for the active brand
kreel --brand <brand-id> context

# Brands your key can reach
kreel brands

# Publish a local HTML report
kreel --brand <brand-id> publish ./monthly-report.html --title "June 2026 performance"

# Installed CLI version
kreel --version

kreel query runs the same allowlisted Query DSL as the MCP query tool and the REST API - only the tables and columns in the DSL’s allowlist can be queried. See the Query DSL reference for the full syntax and allowlist.

kreel publish requires an active brand. Without one, it exits with “Publishing requires a Brand. Pass —brand or configure KREEL_BRAND.” It also rejects files that aren’t .html/.htm, symlinks, and anything over 5 MiB or not valid UTF-8.

Config reference

| Setting | Environment variable | Config key | Default | |---|---|---|---| | API key | KREEL_API_KEY | api_key | none | | Server URL | KREEL_SERVER_URL | server_url | https://api.kreel.ai | | Default brand | KREEL_BRAND | default_brand | none |

An environment variable always overrides the value stored in ~/.kreel/config.toml, which kreel auth login writes.

Errors

| Situation | What you see | |---|---| | No stored key when one is required | Not authenticated. Run: kreel auth login | | API key rejected by the server | Authentication failed. Run: kreel auth login | | Rate limit hit | Rate limit exceeded. Upgrade your plan or try later. | | Can’t reach the server | Cannot connect to <server-url> |

All of these exit with a non-zero status code, so they’re safe to check for in scripts.

What the CLI doesn’t cover

The CLI covers reading your data through the commands above, plus a few things that are MCP-only by design.

• The Brand Knowledge Base write tools (update_brand_profile, update_section, set_competitor, remove_competitor, record_learning, archive_learning) carry write actions that need connector-approval semantics. Use the dashboard’s Brand Knowledge Base page, or an MCP-connected agent, for these.
• The get_entities tool has no CLI equivalent yet. The CLI covers the same ground through its platform-specific commands, like meta campaigns, google campaigns, and klaviyo performance.

MCP prompts and resources - the ready-made prompt library and protocol-level discovery features - are also MCP-only, since they aren’t REST operations. See Connect over MCP for those.

Need help?

Email support@kreel.ai.