Browse docs
On this page
Getting started
Create a customer account and chat as one of its users from your terminal. The astralbeam CLI uses the same API as your backend.
1. Install the CLI
Install globally with Node 22.12 or later, or with Bun:
npm install --global @astralbeam/cliTo run without installing, replace astralbeam below with npx @astralbeam/cli or bunx @astralbeam/cli.
To use a standalone binary instead, follow the binary installation instructions.
2. Sign in
Create an API key as an organization owner or developer. From your application's repository, run the command below and paste the full key_…_abo_… value at the hidden prompt:
cd ~/work/acme
astralbeam auth loginThe CLI verifies the key and remembers the organization for this directory and its descendants. Credentials stay in your private user configuration, outside the repository.
For a self-hosted deployment, pass its /api base. Use HTTPS, or HTTP on localhost for development:
astralbeam auth login --api-url https://beam.example.com/apiCommands print the active organization before their output. To work with another organization, log in from a separate directory.
TIP: In CI, set ASTRALBEAM_API_KEY and, for self-hosting, ASTRALBEAM_API_URL. Environment values override saved login settings.
Confirm the active organization:
astralbeam auth statusCheck that it names the organization you intend to use. See Commands for saved logins and credential storage.
3. Create a Tenant and a user
A Tenant represents one of your customers. Create one with the stable ID your application uses:
astralbeam tenants create --external-id customer-42 --name "Acme Logistics"The output shows the new record, including its internal id. Copy that value, because the TenantUser create command takes it as its first argument:
astralbeam tenant-users create <tenant-id> --external-id user-7 --name "Alex Morgan"Creating the same external ID again fails with HTTP 409. Look records up by external ID instead:
astralbeam tenants list --external-id customer-424. Chat as that user
Send a message as Alex. The default agent replies with its assigned model:
astralbeam chat --tenant customer-42 --user user-7 "What can you help me with?"A reply should stream into the terminal. Omit the message to start interactive chat. See Commands for scripting options, or Coding agents to use the CLI with your coding assistant.