@layers/amba

Amba is the agent-native backend-as-a-service for mobile and web apps. This package is the amba command-line interface.

Install

npm install -g @layers/amba

…or run on demand:

npx @layers/amba init

Requires Node.js 22 or newer.

Agent mode (recommended)

For AI coding agents (Claude Code, Cursor, Windsurf): one command, no browser, no prompts.

npx @layers/amba init --sandbox

This signs up an agent-mode developer account, provisions a project, writes .env.local + AMBA.md, auto-wires mcpServers.amba into every MCP client config it finds on disk, and installs the /amba-build Claude Code skill at .claude/skills/amba-build/SKILL.md.

init keeps credentials out of the repository: .env.local and .amba/project.json hold the project id, client key and API URL (mode 0600), init adds .amba/ and .env*.local to .gitignore, the server key goes to the OS keychain (amba server-key prints it), and an amba entry in a project-local .mcp.json gets Bearer ${AMBA_PAT:-} in place of the PAT.

After restarting your MCP client, paste:

/amba-build <design-url-or-description>

…to scaffold a full Expo app with Amba as the only backend. The skill carries the build prompt inside it, from the CLI that installed it, so it runs the same instructions online and offline; re-run amba init to install a newer prompt. The same text is published at https://docs.amba.dev/prompts/expo-build for reading. Use --no-skills to skip the skill install.

Invite codes

Signup is open, so init needs no invite code. If you have one from an invite email, pass it:

npx @layers/amba init --invite <code-from-your-invite-email>

AMBA_INVITE_CODE works too; the flag wins when both are set. If a code is not valid, or signups are limited, init stops with INVITE_REQUIRED, INVITE_INVALID or SIGNUPS_CLOSED and prints where to request access (https://app.amba.dev/request-access). The invite code arrives by email. With --json, the failure is a JSON document on stdout carrying error.code.

Configure + first call

amba init              # mint a personal project and write .amba/ config
amba login             # browser-based auth, stored in the OS keychain (skip with --token / AMBA_PAT)
amba projects list

Check the project is live:

amba status --detailed

Common commands

amba functions deploy ./functions/hello.ts
amba collections create messages --field user_id:uuid --field body:text
amba types generate                       # emits .amba/types.d.ts
amba secrets set OPENAI_KEY --function hello --from-stdin
amba sites deploy ./out --name marketing

Credentials

amba login and amba init store your token in the operating system's credential store: macOS Keychain, Windows Credential Manager, or the Linux Secret Service. Each API endpoint gets its own entry, so a production login and a staging login (AMBA_API_URL) stay separate:

| | | | --- | --- | | Service | amba | | Account | developer:<api host>, e.g. developer:api.amba.dev | | Value | {"access_token": "…", "refresh_token": "…"} |

When a login replaces a different token for the same endpoint, the replaced one moves to developer:<api host>:previous; the CLI keeps the last three. Non-secret details (developer id, email, endpoint, token expiry, which store holds the token, and a 16-character SHA-256 fingerprint that ties the record to its token) live in ~/.amba/config.json.

amba login (and the browser step of an interactive amba init) signs in through app.amba.dev, so it stores a production session. For another endpoint, set AMBA_PAT to a token from that endpoint, or run amba init --sandbox with AMBA_API_URL set to create an account there.

Where no OS keychain is usable (headless CI, containers, Linux without a Secret Service, or a platform with no prebuilt keyring binary), the CLI stores the token in ~/.amba/credentials.json with mode 0600 and prints one line to stderr naming that file. If the keychain holds your token but cannot be read right now (locked, or access denied), commands stop with an error that names the entry; unlock the keychain or allow access and retry.

Upgrading from a CLI that kept the token in ~/.amba/credentials.json: the first command that reads credentials moves the token into the keychain, reads it back to confirm, and then deletes the file. If the keychain write fails, the file stays as it was and the CLI keeps using it. Earlier versions may also have left ~/.amba/credentials.json.bak-<timestamp> copies; they hold plaintext tokens, so delete them once you no longer need them.

The CLI picks a token in this order:

1. --token <pat>
2. AMBA_PAT environment variable
3. The OS keychain entry for the active endpoint
4. ~/.amba/credentials.json, used only where no keychain is usable

Project server keys live in the same keychain (account server-key:<api host>:<project id>), or in ~/.amba/server-keys.json with mode 0600 where no keychain is usable. amba server-key prints the key of the project linked in the current directory.

amba whoami          # who the active credential belongs to, and where it is stored
amba token           # print the token for scripts: PAT=$(amba token)
amba logout          # remove the keychain entries (and any fallback file entries)

amba token, amba whoami and amba logout exit 1 when nothing is stored and 2 when the keychain holds a token it cannot reach right now. amba logout signs out of the active endpoint only; set AMBA_API_URL to sign out of another one.

Session renewal

amba login stores a browser session: an access token valid for 24 hours from when it was issued, and a refresh token that lasts 30 days and is replaced on every use. The CLI renews the session before a request when the access token expires within five minutes (the expiry comes from the token itself), and once more after a 401 INVALID_DEVELOPER_TOKEN. The new tokens go back to the keychain (or the fallback file), and the new expiry to ~/.amba/config.json. Concurrent commands share a lock file in ~/.amba, so only one of them talks to the refresh endpoint. amba token renews an expired session before printing it; amba whoami shows the expiry and whether it renewed the session. A session that can no longer be renewed prints one line telling you to run amba login.

Headless / CI

Pass a Personal Access Token via --token <pat> or AMBA_PAT to skip the browser login. The CLI never stores, refreshes or rewrites either one. amba init writes the PAT it works with into the MCP client configs it sets up, since those clients need it to connect. A browser-login session expires within a day and an MCP client cannot renew it, so amba init leaves MCP configs alone for a session and prints how to wire a PAT (amba init --token <pat>).

Docs

Full reference: https://docs.amba.dev/cli.

License

Apache-2.0