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 claim <email>

Bind a sandbox account to a real email address via a one-click magic link. Sandbox accounts are minted with an auto-generated address (sandbox-<epoch>-<nonce>@layers.com) and capped at 100 MAU / 10 MB DB until claimed. Running amba claim <email> emails a single-use magic link to the address you pass in; clicking it updates developers.email AND flips the project tier from agent_sandbox to verified_free (1,000 MAU, 500 MB DB).

amba claim me@example.com

The CLI prints a single confirmation line and exits — the click in the email is the whole flow. No copy-paste tokens, no follow-up commands, no console UI. The link expires in 15 minutes.

Error responses surface as terse one-liners:

• EMAIL_TAKEN — that address already owns another Amba account. Sign in with amba login instead, or pick a different email.
• ALREADY_CLAIMED — this account is already verified. No claim needed.
• 429 — too many claim attempts; wait a minute and retry.

Agents without shell access can call the underlying POST /v1/auth/developer/claim endpoint directly with Authorization: Bearer <pat> and body { "email": "<target>" }.

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 <target>

Bundle a function and deploy it to your project's edge runtime. <target> is either a single file or a directory — a directory resolves its entry by convention (index.ts / index.js / index.mjs) or via --entry. 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
 
# Deploy a directory (entry resolved by convention)
amba functions deploy ./functions/checkout
amba functions deploy ./functions/checkout --entry handler.ts --name checkout

Flags:

• --name <name> — function name (default: the file name without extension, or the directory leaf name).
• --entry <file> — entry file when <target> is a directory (relative to it). Default: index.ts/js/mjs.
• --dry-run — bundle and report size without uploading.
• --public — deploy without the X-Api-Key gate so external webhook senders can call it. You must verify the webhook signature in your handler. Default: private.
• --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"'
amba functions logs greet --since-request-id r_019e55ef1f46 --tail

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.
• --request-id <id> — only show events whose logs mention this request id (e.g. r_...); works with --tail.
• --since-request-id <id> — start the range at the oldest event mentioning this request id and show everything from there onward (searches the last 24h, or your --since/--until window). Composes with --request-id (which filters) and --tail (which anchors the backfill, then streams).
• --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

Infrastructure as code

amba export / amba diff / amba apply manage your project's reusable configuration declaratively — the entities you hand-build once and want to stand up identically elsewhere (dev → prod): remote configs, collection schemas, content libraries + items, currencies, achievements, streaks, challenges, leaderboards, and XP rules. The bundle is configuration only — no secrets, no per-user data — so it's safe to check into version control and diff in a pull request. The default bundle file is amba.config.json (JSON only).

amba export [file]

Write the current project's configuration bundle to disk.

amba export                  # → amba.config.json
amba export prod.config.json

amba diff [file]

Show what amba apply would change (created / updated / skipped per section) without writing. Computed locally by exporting the current project and comparing — there's no server-side dry-run.

amba diff
amba diff --mode merge       # preview what merge mode would update

amba apply [file]

Apply a bundle to the current project. Prints the server's authoritative { created, updated, skipped } per section.

amba apply                   # skip_existing (default — no-op on conflict)
amba apply --mode merge      # refresh existing definitions
amba apply prod.config.json --project <id>

--mode skip_existing (default) no-ops on any definition that already exists; --mode merge refreshes existing definitions. Collections are always create-if-absent (never merged in place). All three commands take --project <id> to target a project other than the one in .env.local.

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.