# Agent Analytics CLI Stop juggling dashboards. Let your agent do it. Analytics your AI agent can actually use — track, analyze, experiment, optimize. ## Quick Start Try the seeded public demo without signing in: ```bash 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 funnel agentanalytics-demo --steps "page_view,signup_started,signup" npx --yes @agent-analytics/cli@0.5.33 --demo experiments list agentanalytics-demo ``` Demo mode fetches a short-lived read-only agent session from the hosted API. It does not write local CLI config and blocks mutating commands before making API requests. Get the fastest path to useful analytics for a project you own: ```bash # 1. Start agent login or signup in the browser npx --yes @agent-analytics/cli@0.5.33 login # 2. Create a project; --domain is the primary surface URL/origin for setup npx --yes @agent-analytics/cli@0.5.33 create my-site --domain https://mysite.com # 3. Watch it live npx --yes @agent-analytics/cli@0.5.33 live # Optional detached login for remote or issue-based agent work npx --yes @agent-analytics/cli@0.5.33 login --detached # Optional: clear local auth and revoke the stored agent session when possible npx --yes @agent-analytics/cli@0.5.33 logout ``` ## Commands ```bash # Setup login Browser approval flow for signup/login login --detached Detached handoff: print approval URL and exit login --detached --wait Detached approval with polling for local shells upgrade-link --detached Print a human Pro payment handoff link upgrade-link --wait Print the handoff link and wait for Pro activation logout Clear local auth and revoke the stored agent session when possible auth status Show local auth path and expiry metadata create --domain Create a project with a primary surface URL/origin and get your tracking snippet projects List all your projects with IDs project Get project details by exact name or ID update Update project name or origins by exact name or ID delete Delete a project by exact name or ID # Analytics all-sites Historical summary across all projects bot-traffic Filtered automated traffic by project or --all stats Overview: events, users, daily trends live [name] Real-time terminal dashboard across all projects insights Period-over-period comparison with trends breakdown --property path Top pages, referrers, UTM sources, countries pages Entry/exit page performance & bounce rates paths --goal Bounded entry-to-goal/drop-off session paths heatmap Peak hours & busiest days funnel --steps-json Structured funnel analysis with raw-vs-strict diagnostics funnel --steps a,b,c Legacy comma-separated funnel steps retention Cohort retention: % of users who return sessions-dist Session duration distribution events Raw event log sessions Individual session records query Flexible analytics query (metrics, group_by, filters) properties Discover event names & property keys properties-received Property keys grouped by received event name context get Read stored goals, activation events, event glossary, and annotations context set --json '{...}' Store compact goals, activation events, glossary, and annotations portfolio-context get Read stored account portfolio context portfolio-context set --json '{...}' Store shared goals, surface roles, milestones, and glossary portfolios list List identity lookup portfolios portfolios create --name "Portfolio" --projects app,docs [--move] Create a project portfolio; --move allows reassigning projects portfolios get Show a portfolio and its member projects portfolios update Update name and/or projects with optional --move portfolios delete Delete a portfolio # Experiments — A/B testing your agent can actually use experiments list List experiments experiments create Create experiment experiments get Get experiment with results & significance experiments complete Ship the winner # Session replay — explicit opt-in; Pro or complimentary projects replays settings Show replay settings, privacy defaults, and limits replays enable Enable server eligibility; separate replay.js installation is still required replays disable Stop new starts and upload authorizations replays list [project] List bounded replay metadata; add --session to find linked segments replays get Get one replay and its committed chunk boundaries replays open Print a short-lived sandboxed viewer URL replays open --session --project Find the newest linked segment and open it replays delete Delete one replay immediately replays delete --all --confirm delete_replay_data [--project ] Disable replay and delete all matching replay data replays usage Show retained storage and rolling 30-day ingestion # Account whoami Show current account & tier feedback --message "..." Send product/process feedback logout Clear local auth and revoke the stored agent session when possible ``` The CLI is agent-session-first. It stores a renewable Agent Analytics session after browser approval and uses that bearer auth for CLI API calls. By default, macOS and Windows store the session secret in the OS keychain; Linux and headless environments use the CLI config file. Existing file-stored sessions migrate automatically to native storage on the next authenticated command when native storage is available. Runtime-specific HTTP integrations should stay tied to the approved agent session, project setup, and project context rather than treating the CLI as a manual key setup path. Replay commands require agent-session scopes `replays:read` and `replays:write`. If the saved session predates replay support, run `login` again to approve the added scopes. Replay remains disabled by default even for eligible accounts, and enabling it does not modify or activate the base tracker. A customer must separately install: ```html ``` Use `--recording-start after_consent` when recording must wait for site consent, then call `window.aaReplay.consent()` from the site's consent flow. All form/contenteditable values remain mandatorily masked. Use `--mask`, `--block`, and `--ignore` for comma-separated domain-specific selectors; automatic PII redaction is defense in depth, not a substitute for those selectors. For sites with CSP, allow the Agent Analytics API in `script-src` and `connect-src`, the account R2 S3 endpoint (`https://.r2.cloudflarestorage.com`) in `connect-src`, and `blob:` in `worker-src`. Replay fails closed when those permissions or required browser capabilities are unavailable. Check local storage state without printing secrets: ```bash npx --yes @agent-analytics/cli@0.5.33 auth status ``` Credential storage is automatic. Only use `AGENT_ANALYTICS_CREDENTIAL_STORE` for troubleshooting or managed runtimes: - `file`: force config-file storage - `native`: require OS keychain and fail if unavailable - `auto`: default; usually not needed When a free account hits a Pro-only analytics task, run an explicit upgrade handoff: ```bash npx --yes @agent-analytics/cli@0.5.33 upgrade-link --detached \ --reason "Need funnel and retention reads for this analysis" \ --command "npx --yes @agent-analytics/cli@0.5.33 funnel my-site --steps page_view,signup,purchase" ``` The CLI prints an `app.agentanalytics.sh` link. The human confirms the logged-in dashboard account, pays in Lemon Squeezy, and returns to the agent after Pro activates. Use `upgrade-link --wait` when the local shell should keep polling for activation. Project management commands accept exact project names or project IDs. The `--domain` value on `create` remains the required primary surface URL/origin for setup; it is not the project identity. For local browser QA, treat localhost and preview deployments as setup/testing surfaces and update allowed origins through the CLI while keeping the production origin: ```bash npx --yes @agent-analytics/cli@0.5.33 update stylio --origins 'https://stylio.app,http://lvh.me:3101' ``` For tracker setup, start from the product action you want your agent to optimize. Do not add custom duplicates for automatic tracker signals such as `page_view`, path, referrer, UTMs, device/browser fields, country, session IDs, session count, days since first visit, or first-touch attribution. Prefer `data-aa-event`, `data-aa-impression`, `window.aa.track(...)`, server-side durable outcome tracking, or script opt-ins only when they unlock a concrete decision. Bounce metrics (`insights`, `pages`, `sessions`) treat a session as a bounce when it has only non-interactive events: `page_view`, `$impression`, `$scroll_depth`, `$error`, `$time_on_page`, `$performance`, `$web_vitals`. `query` keeps `/events` raw and lossless, but `/query` uses activation-safe dedupe (`session_then_user`) as the default for `event_count`: session-backed rows count by session, no-session rows fall back to `user_id` only when that user has no session-backed row in the same filtered/grouped result set, and fully anonymous rows fall back to event `id`. For recent signup or ingestion debugging, check `events --event ` first, then use `query` after verifying the raw event names the project emits. `--count-mode` only affects `event_count`. Use `--count-mode raw` when you need the old ingested-row count for debugging or audit work: ```bash npx --yes @agent-analytics/cli@0.5.33 query my-site --metrics event_count --count-mode raw ``` `funnel` is for ordered conversion, `query` is for aggregate slicing/grouping, and `paths` is for bounded session-local journey exploration. For precise funnels, prefer structured JSON steps with per-step filters: ```bash cat > funnel.json <<'JSON' { "steps": [ { "event": "page_view", "filters": [{ "field": "properties.path", "op": "prefix", "value": "/products" }] }, { "event": "add_to_cart" }, { "event": "purchase" } ] } JSON npx --yes @agent-analytics/cli@0.5.33 funnel shop --steps-json ./funnel.json --json ``` Funnel filters use canonical `properties.` fields and support `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `contains`, `prefix`, and `in`. The JSON output includes `steps_source`, `identity_basis`, `raw_activity`, `joinable_entities`, `strict_survivors`, `conversion_rates`, `warnings`, and `caveats` so your agent can separate “events exist” from “entities survived the strict ordered funnel.” `--steps a,b,c` remains supported for quick legacy checks. If no step source is passed, or if you pass `--from-context`, the API falls back to bare `project_context.activation_events`; treat that as a convenience starting point, not a precision source. `paths` accepts bounded lookback windows `1d`, `7d`, `14d`, `30d`, and `90d`. Use `1d` for fresh local instrumentation checks, then move to a longer window once there is enough traffic. Property filters must use canonical `properties.*` fields. Built-in filter fields are only `event`, `user_id`, `date`, `country`, `session_id`, and `timestamp`. Example: ```bash npx --yes @agent-analytics/cli@0.5.33 query my-site --filter '[{"field":"properties.referrer","op":"contains","value":"clawflows.com"}]' ``` Invalid filter fields now fail loudly and return property discovery guidance instead of being silently ignored. Identity lookup with `--email` sends the normalized email to Agent Analytics over HTTPS for server-side project-scoped HMAC matching. The CLI no longer computes or sends a local `email_hash`; raw email is not stored in event rows or profile traits. Store compact project context when the product has custom goals, activation events, event meanings, or date annotations that should travel with analytics results. Keep this short because project-scoped analytics endpoints include it as `project_context`. `context set` accepts an encoded JSON body up to 512KB. 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 the glossary, inspect the project's current event names: ```bash npx --yes @agent-analytics/cli@0.5.33 properties my-site npx --yes @agent-analytics/cli@0.5.33 properties-received my-site npx --yes @agent-analytics/cli@0.5.33 context set my-site --json '{ "goals": ["Increase activated Agent Analytics 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." } ] }' ``` ## Feedback Use the CLI feedback command when Agent Analytics was confusing, a task took too long, or the agent had to do manual analysis that the product should have handled: ```bash npx --yes @agent-analytics/cli@0.5.33 feedback \ --message "The agent had to calculate the funnel drop-off manually" \ --project my-site \ --command "agent-analytics funnel my-site --steps page_view,signup,purchase" \ --context "Share the use case and friction, but avoid private owner details, secrets, or raw customer data." ``` Feedback goes to a real agent via Telegram, every request is seen and auto-approved, and useful fixes can land quickly, sometimes within hours. ## Works With Claude Code, OpenClaw, Cursor, Codex — any AI agent that can run `npx`. Or add the MCP server for rich charts in Claude Desktop: ```bash claude mcp add agent-analytics --transport http https://mcp.agentanalytics.sh/mcp ``` For managed, issue-based, or remote runtimes that cannot receive a localhost callback or keep a long-running process alive, use `npx --yes @agent-analytics/cli@0.5.33 login --detached`. It prints the approval URL and exits. After browser approval, resume with the printed `login --auth-request --exchange-code ` command. For managed runtimes where the default home config path may not persist, point auth storage at a persistent runtime/workspace directory: ```bash 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 ``` For one-off commands, use `--config-dir "$PWD/.openclaw/agent-analytics"` before or after the command. The CLI stores the same `config.json` file in that directory and does not migrate credentials from the default path. For a local shell where it is useful to keep waiting, use `npx --yes @agent-analytics/cli@0.5.33 login --detached --wait`. If your saved session predates CLI `0.5.9`, run a fresh login before calling `projects`. Older saved agent-session tokens were minted without `projects:read`, so they will keep failing until you re-authenticate. Verify with: ```bash npx --yes @agent-analytics/cli@0.5.33 projects ``` ## Agent Skill The installable Agent Skill lives in the canonical public repo: ```bash npx skills add agent-analytics/skills ``` Do not install the skill from this CLI repo. This package is the runtime CLI; the public skill definition is maintained separately so install instructions stay consistent across Codex, Cursor, Claude Code, and other Agent Skills-compatible tools. ## Environment Variables | Variable | Description | |----------|-------------| | `AGENT_ANALYTICS_CONFIG_DIR` | Directory containing CLI `config.json`; use a persistent path in managed runtimes | | `AGENT_ANALYTICS_URL` | Custom API URL (for self-hosted) | | `AGENT_ANALYTICS_DASHBOARD_URL` | Custom dashboard URL for local upgrade-link testing | | `AGENT_ANALYTICS_CREDENTIAL_STORE` | Optional credential storage override: `auto` (default), `native`, or `file` | ## Links - **Dashboard:** https://app.agentanalytics.sh - **Docs:** https://docs.agentanalytics.sh - **Website:** https://agentanalytics.sh - **GitHub:** https://github.com/Agent-Analytics - **Self-host:** https://github.com/Agent-Analytics/agent-analytics - **Agent Skill:** https://github.com/Agent-Analytics/skills ## License MIT