Commands

This page is the reference for every astralbeam command, its output, and its exit codes. astralbeam <command> --help prints the same flags from the installed version.

Global options

ASTRALBEAM_API_KEY wins when it is set, with ASTRALBEAM_API_URL or https://app.astralbeam.ai/api as its URL. Otherwise the CLI uses the login bound to the nearest directory at or above the working directory, and fails when there is none. Every keyed command reports that organization on stderr, as a leading ▸ <name> (<slug>) · org <id> · bound at <directory> line, or as context in the JSON object with --json. API URLs must use https://, except for localhost. ASTRALBEAM_CONFIG_DIR moves the file that holds the bindings.

auth

The CLI never takes a key as a flag, so it cannot leak into shell history or process listings. login and status store the organization's name and slug as the API reports them, and status refreshes them after a rename.

tenants

tenant-users

Updates change only the fields you pass. --metadata takes a JSON object and replaces the stored object whole. The stored admin flag is data and grants no API authority. See Authentication.

Listing options

Both list commands take the same options, which map onto the API's pagination:

In table mode, the CLI prints the next --page-after value on stderr when more results remain. --all spends one request per page against the key's limit of 100 requests per 5 minutes.

token

token chat also takes --tenant-name, --user-name, and --admin, which signs user.admin: true. Both take --expires-in <seconds>, from 60 to 600 and 300 by default. Tokens are signed offline with your key, so minting one makes no request and creates no records.

chat

astralbeam chat --tenant <external-id> --user <external-id> [--agent <agent-id>] [message]

chat runs one turn with the message argument, or with stdin when it is piped, and otherwise opens an interactive prompt that /exit closes. It uses the organization's default agent unless --agent agent_<organizationId>_<id> names another. Like the widget, it synchronizes the signed Tenant and TenantUser records through POST /api/v1/me before chatting. The identity flags match token chat.

The CLI implements no host tools or widgets. A tool the agent calls on the client side is announced on stderr and settled as an error before the next message.

skill

See Coding agents.

Output and exit codes

Without --json, lists print as tables and records as key value lines. With --json, stdout carries exactly what the API returned: a record, or a page with items, page_after, and page_before. token prints { "token", "expires_at" }, and chat prints { "messages": [...] } with the turn's user and assistant messages.

Failures always go to stderr. With --json, stderr holds exactly one JSON object: {"context": {...}} on success, or {"error": {...}, "context": {...}} on failure, where error holds the API's problem details with status, title, detail, and any field issues. context is { "organization", "bound_directory" }, with bound_directory null for ASTRALBEAM_API_KEY, and context itself is null when a command uses no credentials or failed before resolving them.