Browse docs
On this page
Commands
Look up commands, output formats, and exit codes here. For flags supported by your installed version, run astralbeam <command> --help. See Getting started for installation and login.
Global options
Set ASTRALBEAM_API_KEY for CI or use a saved login locally. Environment credentials take precedence, and ASTRALBEAM_API_URL overrides the saved URL. The default API is https://astralbeam.ai/api. Other deployments require HTTPS, except for HTTP on loopback hosts.
auth
Credentials live in ~/.config/astralbeam/config.json, or %APPDATA%\astralbeam\config.json on Windows, outside your repository. Set ASTRALBEAM_CONFIG_DIR to use another configuration directory. The CLI reads keys from a hidden prompt, stdin, or the environment, never a flag.
logout removes the nearest binding for every directory it covers. It does not revoke the key or clear ASTRALBEAM_API_KEY, which still takes precedence.
tenants
tenant-users
Use --name and --metadata for profile fields, and command --help for other options. Updates change only supplied fields. --metadata replaces the entire stored JSON object. The stored admin flag grants no API authority. See Authentication.
Listing options
Tenant and TenantUser 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. Each call returns one page.
Both create and update accept --body '<json>' or --body @file.json instead of individual body flags. Clear a name with --body '{"name":null}'.
For generated API commands, --dry-run previews the request without sending it. This reads local configuration and any supplied @file, but does not validate against the server.
Organization, conversations, and usage
Read organization details, saved conversations, and TenantUser usage through commands generated from the API:
Use the internal UUIDs returned by the API. Conversation lists and message history accept the listing options. Reading history does not make you a conversation participant. Usage takes up to 100 comma-separated user UUIDs and timezone-qualified ISO 8601 timestamps over a positive range of at most 93 days. The start is inclusive and the end exclusive.
token
Tokens last five minutes by default and are signed locally, without creating records. Run the command with --help for identity and expiry options. Use token chat --admin only for a trusted Tenant administrator, since it grants admin API access.
chat
astralbeam chat --tenant <external-id> --user <external-id> [--agent <agent-id>] [message]Pass a message or pipe one through stdin for a single turn. Omit both for interactive chat, and use /exit to leave. Chat uses the default agent unless you pass --agent, and synchronizes the Tenant and TenantUser before sending.
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, records as key value lines, tokens as plain JWTs, and chat replies as streamed text. With --json, records and pages retain the API format. Tokens print { "token", "expires_at" } and chat prints { "messages": [...] } for the turn. JSON chat requires a message argument or piped stdin.
Non-interactive JSON operations write one stderr object: {"context": {...}} on success or {"error": {...}, "context": {...}} on failure. Context identifies the organization and bound directory. API errors retain their problem details, while runtime and usage errors provide error.detail. Help and version output stay plain text.
Use auth status --json to verify the organization before an automated write. Omit --debug when parsing stderr as JSON, since it adds HTTP logs and stack traces. After a timeout or failed write, check the result before retrying.