CLI Reference

The Amba CLI helps you initialize projects, check status, test push notifications, and manage remote config from your terminal.

Installation

The CLI has two install paths today. Path A (monorepo) is the reality; Path B (npm) lights up once the package ships.

Path A — from the monorepo (today)

The Amba monorepo exposes the CLI as a workspace script. From the repo root:

pnpm install
pnpm -r run build
pnpm amba init

The root package.json defines:

{
  "scripts": {
    "amba": "pnpm --filter amba exec node dist/index.js"
  }
}

…so pnpm amba <subcommand> runs the CLI straight from the workspace build. All examples below use pnpm amba.

Path B — npm (coming soon)

Once the amba npm package ships:

# Use directly with npx (no install needed)
npx amba init
 
# Or install globally
npm install -g amba

Commands

`amba init`

Initialize Amba in your current project. Walks you through:

Creating an account or logging in
Creating a new project
Generating API keys
Writing config to your project

pnpm amba init

Authenticate with your Amba account.

pnpm amba login

`amba logout`

Clear stored credentials.

pnpm amba logout

Show project health and integration status. The default view covers authentication, your local .env.local configuration, API key validation, project metadata, and the presence of context files (AMBA.md, Cursor rules).

pnpm amba status

Pass --detailed to add a per-project metrics block:

Integration health (APNS, FCM, RevenueCat, Superwall)
Total user count
Active and total segment counts
24h event total + the top 5 event names by count

pnpm amba status --detailed

If your deployment predates the admin events-count endpoint the metrics block degrades gracefully — events are reported as (unavailable — endpoint not deployed) instead of failing.

`amba logs tail`

Tail the project-wide engagement event log. By default the command fetches the most recent 100 events from the last 24 hours and prints them oldest-to-newest:

pnpm amba logs tail

Each line is <timestamp> <event_name> user=<user_id> <properties>.

Useful flags:

--follow — keep the connection open and poll every 2 seconds for new events. Press Ctrl-C to stop cleanly.
--json — emit raw NDJSON (one event per line) for piping into jq, Vector, or any downstream pipeline. Banner output is suppressed.
--since <iso> — only show events on or after the given ISO 8601 timestamp (default: 24h ago).
--event-name <name> — filter to a single event name.
--user-id <id> — filter to events for a single app user.
--limit <n> — events per page (default 100, max 1000).
--project <id> — override the project id from .env.local.

# follow new events for a single user
pnpm amba logs tail --user-id u_abc --follow
 
# pipe NDJSON into jq
pnpm amba logs tail --json --limit 1000 | jq 'select(.event_name == "purchase")'

`amba push test`

Send a test push notification to all registered devices for your project.

pnpm amba push test

`amba config list`

List all remote config values for your project.

pnpm amba config list

`amba config set <key> <value>`

Set a remote config value.

pnpm amba config set daily_limit 10
pnpm amba config set feature_paywall_v2 true

`amba analytics export`

Bulk-export users or events to CSV (default) or NDJSON. Both flows are backed by streaming admin endpoints, so you can dump millions of rows without buffering the result set in memory.

# Export every user as CSV to stdout (uses /admin/.../users/export stream)
pnpm amba analytics export --type=users > users.csv
 
# Export the last 7 days of events to a file as NDJSON
pnpm amba analytics export \
  --type=events \
  --since 2026-04-17T00:00:00Z \
  --format=ndjson \
  --out events.ndjson

Flags:

--type=users|events — required. Switches between the two exporters.
--since <iso> / --until <iso> — time window for events (defaults: last 24 hours). The users export honors --since against created_at.
--format=csv|ndjson — output encoding. CSV is the default.
--out <file> — write to disk instead of stdout. The command tees a progress counter to stderr so it stays usable when redirecting stdout.
--limit <n> — per-page row limit when paginating events (default 1000). The command keeps walking cursors until the server reports no more rows.
--project <id> — override the project id from .env.local.

The events exporter uses the project-wide /admin/projects/:projectId/events cursor pagination introduced in Wave 5 — there's no longer an N+1 fan-out across users.

Authentication

The CLI stores credentials locally after amba login. All commands that require authentication use the stored credentials automatically.

Credentials are stored in ~/.amba/credentials.json.