CLI

The Agent Analytics CLI is the official shell-first wrapper around the documented HTTP API. Use it when your AI agent already has terminal access and you want predictable command output with lower overhead than MCP-style tool calls.

The published package is @agent-analytics/cli. For one-off use, run it through npx with a pinned version:

npx --yes @agent-analytics/cli@0.5.33 --help

Source repo: Agent-Analytics/agent-analytics-cli

In the rest of this page, agent-analytics means the CLI binary from that same package and version.

When to use the CLI

Choose the CLI when:

your agent already works in a shell-first environment
you want a thin wrapper over the hosted API instead of a connector flow
you want command composition and scripting instead of tool-call round trips
you want local auth helpers such as login, logout, whoami, and auth status

If you are deciding between access paths rather than looking for CLI usage itself, start with Skill vs MCP vs API.

Use the seeded public demo when you want an AI agent to try the real CLI/API workflow before you connect an account:

npx --yes @agent-analytics/cli@0.5.33 demo
npx --yes @agent-analytics/cli@0.5.33 --demo projects
npx --yes @agent-analytics/cli@0.5.33 --demo stats agentanalytics-demo --days 30
npx --yes @agent-analytics/cli@0.5.33 --demo paths agentanalytics-demo --goal signup --since 30d
npx --yes @agent-analytics/cli@0.5.33 --demo funnel agentanalytics-demo --steps "page_view,signup_started,signup"
npx --yes @agent-analytics/cli@0.5.33 --demo breakdown agentanalytics-demo --property path --event signup_started --days 30
npx --yes @agent-analytics/cli@0.5.33 --demo breakdown agentanalytics-demo --property path --event signup --days 30
npx --yes @agent-analytics/cli@0.5.33 --demo experiments get exp_demo_signup_cta

Useful prompts:

“Audit the signup leak, question the data, and tell me the next fix to test.”
“Check whether the CTA experiment winner actually fixes the biggest signup problem.”
“Turn the demo analytics into a developer-ready growth task with metrics and guardrails.”

--demo fetches a short-lived read-only aas_* session from POST /demo/session, then runs normal read commands against the hosted agentanalytics-demo project. It does not expose a raw aak_* API key, does not read or write your saved CLI config, and blocks mutating commands locally.

Website analysis compatibility

scan exists for authenticated operator workflows and scanner-informed setup previews. It is not the normal setup center for agents that can inspect the product repo. For normal setup, create or identify the project, confirm the initial product goal, install the project-owned tracker, add intentional events tied to that goal, and verify the first useful event.

When a scan is used, treat the scanned URL as a project surface, not as the project identity. Read minimum_viable_instrumentation, confirm the user goal before storing durable context, install only recommendations tied to that goal, then verify the first useful event with events.

Public browser previews analyze only the root domain. They do not create an aas_* agent session. CLI scan creation and project linking require login and a project, except for internal complimentary-account workflows.

npx --yes @agent-analytics/cli@0.5.33 login
npx --yes @agent-analytics/cli@0.5.33 create my-site --domain https://mysite.com
npx --yes @agent-analytics/cli@0.5.33 scan https://mysite.com --project my-site --json
npx --yes @agent-analytics/cli@0.5.33 events my-site --event <first_useful_event> --days 7 --limit 20

The JSON output is stable for agent skills. Agents should install only the high-priority minimum_viable_instrumentation first and verify the first useful recommended event with events.

Each recommendation includes an implementation_hint mapped to tracker.js capabilities. Page views, paths, referrers, UTMs, device/browser fields, country, session IDs, session count, days since first visit, and first-touch attribution are automatic, so agents should not add custom duplicates for those signals. Use data-aa-event for named click intent, data-aa-impression for meaningful section exposure, window.aa.track(...) for computed client state, server-side tracking for durable outcomes such as completed signup, and broad script opt-ins only when they unlock the stated decision.

The CLI is agent-session-first:

default: agent-analytics login opens browser approval with a local loopback callback
detached handoff: agent-analytics login --detached prints an approval URL and exits so issue-based or remote runtimes can resume with a finish code
optional polling: agent-analytics login --detached --wait keeps the process alive for local shells that can wait for browser approval

Do not ask users to paste long-lived API keys into an agent thread. Browser approval is the normal hosted flow.

The CLI stores local config at $XDG_CONFIG_HOME/agent-analytics/config.json, with fallback to ~/.config/agent-analytics/config.json.

For managed agent runtimes where home-directory config may not persist, set an explicit persistent directory before login:

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/cli@0.5.33 login --detached
npx --yes @agent-analytics/cli@0.5.33 auth status

You can also pass --config-dir "$PWD/.openclaw/agent-analytics" before or after any command. Resolution order is: --config-dir, AGENT_ANALYTICS_CONFIG_DIR, $XDG_CONFIG_HOME/agent-analytics, then ~/.config/agent-analytics.

Credential lookup still respects compatibility environment overrides first, so AGENT_ANALYTICS_API_KEY continues to win until you unset it.

Pro upgrade handoff

Free accounts can prove the workflow with core setup and basic reads. Pro unlocks deeper agent analysis: funnels, retention, sessions, pages, heatmaps, insights, live reads, experiments, no monthly agent/API read cap, no monthly event cap, and 365-day retention.

When a CLI command returns PRO_REQUIRED or a free-tier read cap, ask the agent to create a human payment handoff:

agent-analytics upgrade-link --detached \
  --reason "Need funnel and retention reads for this analysis" \
  --command "agent-analytics funnel my-site --steps page_view,signup,purchase"

upgrade-link --detached prints an app.agentanalytics.sh link and exits. The human opens the link, the dashboard confirms the logged-in account, Lemon Squeezy handles payment, and the webhook activates Pro.

Use upgrade-link --wait when the local shell should keep polling until whoami would show Pro.

Common commands

agent-analytics projects
agent-analytics whoami
agent-analytics auth status
agent-analytics create my-site --domain https://mysite.com
agent-analytics stats my-site --days 7
agent-analytics insights my-site --period 7d
agent-analytics events my-site --days 7 --limit 20
agent-analytics context get my-site
agent-analytics context set my-site --json '{"goals":["Increase activated accounts"],"activation_events":["signup_completed","project_created","first_event_received"],"glossary":[{"event_name":"first_event_received","term":"AA Activation","definition":"Signup, project created, and first event received."}],"annotations":[{"occurred_at":"2026-04-25T13:00:00.000Z","title":"Changed pricing page offer"}]}'
agent-analytics breakdown my-site --property path --event page_view --days 7 --limit 10
agent-analytics paths my-site --goal signup --since 30d --max-steps 5
agent-analytics funnel my-site --steps "page_view,signup,purchase"
agent-analytics retention my-site --period week --cohorts 8
agent-analytics experiments list my-site
agent-analytics logout

The main command families are:

account and auth: login, logout, whoami, auth status, upgrade-link
project setup: scan, create, projects
reporting: stats, insights, breakdown, pages, paths, sessions-dist, events, sessions, query
live monitoring: live
schema and context: properties, properties-received, context get, context set
analysis workflows: funnel, retention, experiments
product feedback: feedback

Scoped agent sessions cannot generate or rotate raw account API keys; manage compatibility keys from the dashboard.

Project management

projects prints each project’s name, ID, project token, and allowed origins. project, update, and delete accept either the exact project name or the project ID.

Use update to change allowed origins without leaving the CLI. The --domain value on create is the required primary surface URL/origin for setup and allowed-origin checks; it is not the project identity. For local browser QA, treat localhost and preview deployments as setup/testing surfaces: keep the production origin and add the temporary local or preview origin:

agent-analytics update stylio --origins 'https://stylio.app,http://lvh.me:3101'

Project context

Use context get and context set when a project has custom goals, activation events, event meanings, or date annotations that should travel with analytics results.

Project context is intentionally compact. Project-scoped analytics result endpoints return it as project_context when it is non-empty, so long notes would make every agent read noisier.

The stored shape is:

goals: up to 5 short business goals
activation_events: up to 8 event names that define activation or the main success path
glossary: up to 10 entries, each with event_name, term, and definition
annotations: up to 100 entries, each with occurred_at, title, and optional note

context set accepts an encoded JSON request body up to 512KB. Individual entries are also capped: goals at 160 characters, event names at 96 characters, glossary terms at 64 characters, glossary definitions at 240 characters, annotation titles at 120 characters, and annotation notes at 500 characters.

Use annotations for major product changes that could explain later graph movement: landing page, pricing, onboarding, feature, release, or experiment changes. Do not store git commit logs, noisy edits, temporary metric notes, PII, secrets, or long release notes. Direct context get returns all annotations; project-scoped analytics responses include annotations only for the requested analytics date range plus one day before and after.

Before setting or refreshing a glossary, inspect the project’s real event names:

agent-analytics properties my-site
agent-analytics properties-received my-site

Then store the compact context:

agent-analytics context set my-site --json '{"goals":["Increase activated accounts"],"activation_events":["signup_completed","project_created","first_event_received"],"glossary":[{"event_name":"first_event_received","term":"AA Activation","definition":"Signup, project created, and first event received."}],"annotations":[{"occurred_at":"2026-04-25T13:00:00.000Z","title":"Changed pricing page offer","note":"Moved annual plan discount above the fold."}]}'

Read it back with:

agent-analytics context get my-site

Identity portfolios

Use portfolios when several related projects should share a privacy-first customer lookup boundary and be interpreted as one growth system. In the product model, a portfolio connects related projects while each project keeps its own events, activation, retention, lifecycle, releases, experiments, and local goals. Surfaces are the places users encounter or use those projects. See Projects, surfaces, and portfolios for the canonical model.

An identity portfolio is the server-side scope for cross-project identity-aware reads and email lookup when configured within intentionally grouped portfolio projects. It does not merge every project in an account automatically, and it does not replace project-local truth.

Cross-project identity needs both setup steps:

add data-link-domains to each participating tracker snippet so the browser passes _aa across related surface domains
add those Agent Analytics projects to the same identity portfolio so hosted analytics resolves intentionally grouped projects in the same scope

If you only configure data-link-domains, links are decorated but separate projects remain isolated. If you only configure a portfolio, the server has a shared scope but the browser has no anonymous ID to carry across domains.

A good fit is a setup like one portfolio with separate projects for related growth loops:

agentanalytics.sh → scanner and conversion surface
openorchestrators.org → discovery surface
clawflows.com → ecosystem discovery surface

Example:

agent-analytics portfolios create growth-system \
  --name "Growth system" \
  --projects agentanalytics.sh,openorchestrators.org,clawflows.com

Manage it with:

agent-analytics portfolios list
agent-analytics portfolios get growth-system
agent-analytics portfolios update growth-system --projects agentanalytics.sh,openorchestrators.org,clawflows.com --move

The older portfolio-context commands only store compact account-level interpretation notes. Use portfolios for the public identity lookup and membership contract.

After a real source-to-destination click, verify the destination project:

agent-analytics query agentanalytics.sh \
  --metrics event_count,unique_users \
  --filter '[{"field":"properties.referrer","op":"contains","value":"clawflows.com"}]' \
  --days 1

CLI to API mapping

Most CLI workflows map directly to an HTTP endpoint. Auth convenience commands such as logout also update local CLI state and may perform best-effort session cleanup.

CLI Command	API Endpoint
`agent-analytics stats my-site`	`GET /stats?project=my-site`
`agent-analytics all-sites --period 7d`	`GET /account/all-sites?period=7d`
`agent-analytics bot-traffic my-site --period 7d`	`GET /bot-traffic?project=my-site&period=7d`
`agent-analytics bot-traffic --all --period 7d`	`GET /account/bot-traffic?period=7d`
`agent-analytics events my-site`	`GET /events?project=my-site`
`agent-analytics events my-site --email [email protected]`	`POST /events/lookup` with `{ project, email }`
`agent-analytics journey my-site --email [email protected]`	`POST /journey/lookup` with `{ project, email }`
`agent-analytics context get my-site`	`GET /project-context?project=my-site`
`agent-analytics context set my-site --json '{...}'`	`PUT /project-context`
`agent-analytics portfolios list`	`GET /portfolios`
`agent-analytics portfolios create growth --name Growth --projects app,docs`	`POST /portfolios`
`agent-analytics portfolios get growth`	`GET /portfolios/{idOrSlug}`
`agent-analytics portfolios update growth --projects app,docs --move`	`PATCH /portfolios/{idOrSlug}`
`agent-analytics query my-site --metrics event_count`	`POST /query`
`agent-analytics query my-site --metrics event_count --count-mode raw`	`POST /query`
`agent-analytics paths my-site --goal signup`	`POST /paths`
`agent-analytics funnel my-site --steps "page_view,signup,purchase"`	`POST /funnel`
`agent-analytics retention my-site --period week --cohorts 8`	`GET /retention?project=my-site&period=week&cohorts=8`
`agent-analytics experiments list my-site`	`GET /experiments?project=my-site`
`agent-analytics experiments create my-site --name signup_cta --variants control,new_cta --goal signup`	`POST /experiments`
`agent-analytics experiments get exp_abc123`	`GET /experiments/{id}`
`agent-analytics scan https://mysite.com --project my-site --json`	`POST /cli/website-scans`
`agent-analytics scan https://mysite.com --full --project my-site --json`	`POST /cli/website-scans`
`agent-analytics projects`	`GET /projects`
`agent-analytics project my-site`	`GET /projects/{id}` after resolving name or ID
`agent-analytics update my-site --origins https://mysite.com`	`PATCH /projects/{id}` after resolving name or ID
`agent-analytics delete my-site`	`DELETE /projects/{id}` after resolving name or ID
`agent-analytics logout`	Clears saved CLI auth and, when a stored agent session ID and usable token material are available, best-effort revokes that agent session.

logout clears the auth state saved by the CLI on disk and may revoke the stored agent session. It is not logout-all-devices. Browser /auth/logout is POST-only, clears only the current browser session, and does not disconnect CLI agents. To disconnect selected agent sessions explicitly, use Dashboard Settings / Agent Sessions.

Query caveats

The canonical CLI syntax is agent-analytics query <project> .... Do not use --project.
Use journey <project> --user-id <id> or journey <project> --email <email> when you need one customer timeline. Email lookup sends the raw email over HTTPS in an authenticated POST body so the server can match a project/portfolio-scoped HMAC lookup index.
Raw email may be transmitted during identify or authenticated lookup, but Agent Analytics does not store it raw in event rows or profile traits. Do not send browser-side SHA-256 hashes or email_hash payloads; they are no longer part of the public CLI/API contract.
/events stays raw and lossless. /query uses session_then_user as the default for event_count.
For recent signup or ingestion debugging, check events <project> --event <actual_event_name> first; add --user-id or --email when you want the raw rows for one identity.
Use --count-mode raw when the question is about ingestion volume or duplicate-write debugging rather than activation-safe counts.
Built-in query fields are event, user_id, date, country, session_id, and timestamp.
Non-built-in fields such as referrer, utm_source, path, browser, and hostname must be written as properties.<key>.
group_by is limited to built-in fields only: event, date, user_id, session_id, and country.
If you need low-level payload or filter debugging, move to the API Reference instead of forcing complex shell JSON into the CLI.

CLI