CLI Reference

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

Installation

Use directly with npx — no install required:

npx @layers/amba init

Or install it globally:

npm install -g @layers/amba
amba init

All examples below use the amba <command> form once the CLI is on your PATH. If you prefer npx, prefix every command with npx @layers/amba — the arguments are identical.

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

amba init

amba login

Authenticate with your Amba account.

amba login

amba logout

Clear stored credentials.

amba logout

amba status

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

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

amba status --detailed

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:

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
amba logs tail --user-id u_abc --follow
 
# pipe NDJSON into jq
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.

amba push test

amba config list

List all remote config values for your project.

amba config list

amba config set <key> <value>

Set a remote config value.

amba config set daily_limit 10
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)
amba analytics export --type=users > users.csv
 
# Export the last 7 days of events to a file as NDJSON
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.

amba functions dev <file>

Run a local development server for an Amba function with hot reload on file changes. The dev server reproduces the production request shape so you can iterate before deploying. See Functions → Local dev.

amba functions dev ./functions/hello.ts
# Listening on http://127.0.0.1:8787
# Watching ./functions/hello.ts — save to reload.

Flags:

• --port <n> — port to listen on (default 8787).
• --no-watch — disable file-change hot reload.

amba functions deploy <file>

Bundle a function and deploy it to your project's edge runtime. See Functions → Deploy.

amba functions deploy ./functions/hello.ts
amba functions deploy ./functions/hello.ts --name greet
amba functions deploy ./functions/hello.ts --dry-run

Flags:

• --name <name> — function name (default: filename without extension).
• --dry-run — bundle and report size without uploading.
• --rate-limit-window <60s|5m|1h> — per-function rate-limit window (all three rate-limit flags must be set together or all omitted).
• --rate-limit-max <int> — max requests per window.
• --rate-limit-key <user_id|ip> — bucket key for the rate limit.

amba functions list

List active functions for the current project.

amba functions list

amba functions delete <name>

Remove a function from your project's edge runtime.

amba functions delete greet

amba functions schedule <name> <cron>

Register a cron schedule that invokes a deployed function.

amba functions schedule daily-digest "0 9 * * *" --tz America/New_York

Flags:

• --tz <iana> — IANA timezone for the schedule (default UTC).

amba functions logs <name>

Stream log events for a deployed function.

amba functions logs greet --tail
amba functions logs greet --since 2026-05-15T00:00:00Z --json | jq '.level == "error"'

Flags:

• --since <iso> / --until <iso> — time range (default: last hour).
• --limit <n> — max events per fetch (default 100, max 1000).
• --tail (alias --follow) — keep streaming new events; polls every 3s. Ctrl-C to stop.
• --json — emit NDJSON to stdout for piping into jq.

amba functions consume <queue-name> <function-name>

Bind a function as the consumer for a queue.

amba functions consume orders process-order
amba functions consume orders process-order --paused

Flags:

• --paused — create the binding paused (messages dead-letter until you resume).

amba functions consumers list

List queue bindings for the current project.

amba functions consumers list

amba functions consumers unbind <queue-name>

Remove the binding for a queue.

amba functions consumers unbind orders

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.