@agent-analytics/cli

v0.5.33

Published

7 days ago

Stop juggling dashboards. Let your agent do it. Analytics your AI agent can actually use — track, analyze, experiment, optimize.

0High
0Medium
0Low

support-agentanalytics.sh

dannyshmueli

analytics ai agent cli web-analytics

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:

npx --yes @agent-analytics/[email protected] demo
npx --yes @agent-analytics/[email protected] --demo projects
npx --yes @agent-analytics/[email protected] --demo funnel agentanalytics-demo --steps "page_view,signup_started,signup"
npx --yes @agent-analytics/[email protected] --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:

# 1. Start agent login or signup in the browser
npx --yes @agent-analytics/[email protected] login

# 2. Create a project; --domain is the primary surface URL/origin for setup
npx --yes @agent-analytics/[email protected] create my-site --domain https://mysite.com

# 3. Watch it live
npx --yes @agent-analytics/[email protected] live

# Optional detached login for remote or issue-based agent work
npx --yes @agent-analytics/[email protected] login --detached

# Optional: clear local auth and revoke the stored agent session when possible
npx --yes @agent-analytics/[email protected] logout

Commands

# 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 <name> --domain <url>     Create a project with a primary surface URL/origin and get your tracking snippet
projects                         List all your projects with IDs
project <project>                Get project details by exact name or ID
update <project>                 Update project name or origins by exact name or ID
delete <project>                 Delete a project by exact name or ID

# Analytics
all-sites                        Historical summary across all projects
bot-traffic <name>               Filtered automated traffic by project or --all
stats <name>                     Overview: events, users, daily trends
live [name]                      Real-time terminal dashboard across all projects
insights <name>                  Period-over-period comparison with trends
breakdown <name> --property path Top pages, referrers, UTM sources, countries
pages <name>                     Entry/exit page performance & bounce rates
paths <name> --goal <event>      Bounded entry-to-goal/drop-off session paths
heatmap <name>                   Peak hours & busiest days
funnel <name> --steps-json <arg> Structured funnel analysis with raw-vs-strict diagnostics
funnel <name> --steps a,b,c      Legacy comma-separated funnel steps
retention <name>                 Cohort retention: % of users who return
sessions-dist <name>             Session duration distribution
events <name>                    Raw event log
sessions <name>                  Individual session records
query <name>                     Flexible analytics query (metrics, group_by, filters)
properties <name>                Discover event names & property keys
properties-received <name>       Property keys grouped by received event name
context get <name>               Read stored goals, activation events, event glossary, and annotations
context set <name> --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 <slug> --name "Portfolio" --projects app,docs [--move]
                                 Create a project portfolio; --move allows reassigning projects
portfolios get <slug-or-id>      Show a portfolio and its member projects
portfolios update <slug-or-id>   Update name and/or projects with optional --move
portfolios delete <slug-or-id>   Delete a portfolio

# Experiments — A/B testing your agent can actually use
experiments list <project>       List experiments
experiments create <project>     Create experiment
experiments get <id>             Get experiment with results & significance
experiments complete <id>        Ship the winner

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

Check local storage state without printing secrets:

npx --yes @agent-analytics/[email protected] 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:

npx --yes @agent-analytics/[email protected] upgrade-link --detached \
  --reason "Need funnel and retention reads for this analysis" \
  --command "npx --yes @agent-analytics/[email protected] 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:

npx --yes @agent-analytics/[email protected] 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 <project> --event <actual_event_name> 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:

npx --yes @agent-analytics/[email protected] 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:

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/[email protected] funnel shop --steps-json ./funnel.json --json

Funnel filters use canonical properties.<key> 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:

npx --yes @agent-analytics/[email protected] 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:

npx --yes @agent-analytics/[email protected] properties my-site
npx --yes @agent-analytics/[email protected] properties-received my-site
npx --yes @agent-analytics/[email protected] 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:

npx --yes @agent-analytics/[email protected] 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:

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/[email protected] login --detached. It prints the approval URL and exits. After browser approval, resume with the printed login --auth-request <id> --exchange-code <code> command.

For managed runtimes where the default home config path may not persist, point auth storage at a persistent runtime/workspace directory:

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/[email protected] login --detached
npx --yes @agent-analytics/[email protected] 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/[email protected] 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:

npx --yes @agent-analytics/[email protected] projects

Agent Skill

The installable Agent Skill lives in the canonical public repo:

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 |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme