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.

Project configuration lookup

Project-scoped commands resolve AMBA_PROJECT_ID from the process environment first, then .env.local or .env in the current working directory. The CLI does not walk into parent directories: doing so could silently select a different workspace's credentials in a monorepo or nested checkout.

From a subdirectory, either export AMBA_PROJECT_ID, use --project <id> on commands that expose it, or run the command from the directory containing the intended env file. CI should inject variables from its secret store rather than creating an env file.

Project-scoped CI credentials

For CI that only needs to operate on one existing project, use that project's server key (amb_dev_sk_… / amb_live_sk_…) instead of a developer PAT. The CLI forwards --token verbatim, and project-scoped commands such as sites deploy and functions deploy accept a server key:

amba sites deploy ./dist --name my-site --token "$AMBA_SERVER_KEY"

The API verifies that the project id in the command matches the key's project; a different project returns 403 WRONG_PROJECT. Server keys cannot list or create projects. The --token <pat> placeholder in command help is historical shorthand—the flag also accepts a project server key for these project-scoped commands. Keep server keys in your CI secret store and never commit them.

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.
• --forward-authorization — forward the verified caller's bearer Authorization header to this function. Off by default; X-Api-Key and internal trigger credentials are always stripped.
• --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 deploy-status

Check whether platform maintenance has paused function deploys before starting a release. A paused response includes the same retry interval used by deploy.

amba functions deploy-status

amba functions delete <name>

Remove a function from your project's edge runtime.

amba functions delete greet --confirm greet

--confirm must exactly match the function name. This prevents a typo in a destructive command from deleting a different function.

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 schedules

List every schedule with its cron expression, timezone, pause state, and last/next fire times.

amba functions schedules

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. Provider batches can arrive roughly two minutes after an invocation, so keep the tail open through that ingestion window. Ctrl-C to stop. Successful invocations without console.* output are printed as [outcome] ok.
• --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 domains attach|list|refresh|remove

Manage one exact custom hostname for a deployed function:

amba functions domains attach feed feeds.example.com
amba functions domains list feed
amba functions domains refresh feed feeds.example.com
amba functions domains remove feed feeds.example.com

Attach prints the CNAME target plus ownership and certificate validation records. Publish all returned DNS records, then refresh until both statuses are active and routing reconciliation succeeds (live=true). Paths and query strings are preserved exactly.

This MVP does not support wildcards, path rewrites, or automatic www.feeds.example.com creation. Podcast/feed clients cannot send an Amba API key, so deploy their function with --public and validate any private application token in the handler. See Function Custom Domains.

Effective-tier caps are free 1, pro 5, scale 20, and enterprise/comped 50. Attach allows five attempts per project per hour. An unverified claim becomes eligible for exact-host reclaim after 24 hours; pending claims do not allocate Worker route/KV resources.

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.