@analytickit/cli

analytickit — command-line client for the AgentGraph API. Useful for scripting reports, batch event ingestion from NDJSON files, on-call attribution checks, and any automation that's awkward to express against the dashboard UI.

The binary talks HTTP to the AgentGraph API. By default it goes through the dashboard's /api rewrite at https://app.analytickit.com/api (apps/api itself has no public host yet) using a Bearer API key. Event ingestion goes to a separate ingest endpoint (apps/ingest, default http://localhost:3003) using a per-client SDK key.

Install

npm install -g @analytickit/cli
analytickit --help

Or run it once without a global install:

npx @analytickit/cli --help

From the monorepo (for development)

git clone https://github.com/kitadmin01/agentgraph
cd agentgraph
npm install
npm run build -w @analytickit/db   # the CLI bundles its filter-registry module
npm run build -w @analytickit/cli
node ./packages/cli/dist/index.js --help

For day-to-day development against src/, use the dev runner:

npm run dev -w @analytickit/cli -- clients list
# (everything after `--` is passed to the CLI)

Authenticate

Get an API key from the dashboard (Settings → API Keys → Create API Key). Then:

analytickit auth login
# or non-interactive:
analytickit auth login --key ak_xxxxx

The key is written to ~/.analytickit/config.json with mode 0600. The default API URL is https://app.analytickit.com/api (the dashboard's /api rewrite — api.analytickit.com isn't public yet). Point at a local stack instead with --url or ANALYTICKIT_API_URL=http://localhost:3001:

analytickit auth login --url http://localhost:3001

Verify:

analytickit auth status
# Authenticated as: <agency name>
# API URL: https://app.analytickit.com/api

Command reference

All commands accept the global flags --json (machine-readable output) and --api-url <url> (override the URL stored in config for one call).

Auth

| Command | Description | |---|---| | analytickit auth login [--key <key>] [--url <url>] | Save credentials | | analytickit auth logout | Remove ~/.analytickit/config.json | | analytickit auth status | Verify the stored key by hitting /v1/agency |

Read

| Command | Description | |---|---| | analytickit clients list | All clients in your agency | | analytickit clients get <id> | Detail for one client | | analytickit wallets list --client <id> [--segment <s>] [--limit <n>] | Wallets for a client | | analytickit wallets profile <address> | Cross-chain profile for one wallet | | analytickit campaigns attribution --client <id> [--from <date>] [--to <date>] [--chain <chain>] [--actor-type <type>] | Funnel breakdown | | analytickit traces list [--actor-type <type>] [--from <date>] [--to <date>] [--limit <n>] [--cursor <c>] | Recent execution traces (human, cli, mcp, ai_agent) |

Write

| Command | Description | |---|---| | analytickit clients create --name <name> --chain <chain> [--website <url>] | Create a client | | analytickit report --client <id> --period <days> [--type ad_hoc\|weekly] | Generate a report; --period is days 1-90 with optional d suffix (e.g. 7d, 30); polls every 3 s up to 60 s | | analytickit export pdf --client <id> --report <reportId> [--output <path>] | Download a generated report's PDF |

Ingest

These hit the ingest service, not the API, and use a per-client SDK key (different from your account API key — get it from the dashboard when you create a client).

| Command | Description | |---|---| | analytickit ingest event --client <id> --name <event> --sdk-key <sdkkey> [--properties <json>] [--ingest-url <url>] | One event | | analytickit ingest batch --client <id> --file <ndjson> --sdk-key <sdkkey> [--ingest-url <url>] | Bulk-load NDJSON in chunks of 500 |

Each NDJSON line should be one event object with at minimum event_name; timestamp defaults to "now" if omitted.

Output format

The default is a plain-text table. Pass --json for machine-readable output (the API response is printed verbatim):

analytickit clients list                # table
analytickit clients list --json         # JSON
analytickit traces list --json | jq .   # pipeable

Status messages and progress (Sent 500/1500 events...) print to stderr, so --json output piped to jq stays clean.

Environment overrides

| Env / flag | Effect | |---|---| | --api-url <url> | Override the API base URL for a single command (does not write to config) | | --json | Switch output mode for a single command | | ~/.analytickit/config.json | { apiKey, baseUrl } set by auth login. Mode 600. |

See also

• docs/help/cli-quickstart.md — end-to-end walkthrough (build → login → list → report → PDF).
• apps/dashboard/src/app/(protected)/settings/api-keys/page.tsx — where keys are minted.
• apps/api/src/ — the API the CLI talks to. Endpoint shapes documented inline.

Roadmap

• Publish to npm under @analytickit/cli once we've validated the UX (npm i -g @analytickit/cli).
• Add analytickit logs tail (read from CloudWatch in prod).
• Add analytickit segment list / get / update once segmentation surfaces a write API.