Install the CLI

The asteroid command calls the Asteroid API from your terminal, scripts and CI. It needs Node.js 22 or later.

Install

npm install -g @asteroidai/cli

asteroid login

The CLI prints a code and opens your browser. Confirm the code to sign in. If you belong to more than one organization, pick one.

Check it works

asteroid whoami
asteroid workflow list

Your user, organization and workflows come back.

Organizations

asteroid orgs lists the organizations you can act in. asteroid use <org> sets the default by id or name. --org <org> acts in another organization for one command.

CI and agents

Set ASTEROID_API_KEY instead of signing in. An API key belongs to one organization, so --org does not apply.

export ASTEROID_API_KEY=...
asteroid execution list --json

Add --json to get the API response as JSON. Scripts should read --json, because the text output may change between releases. Exit codes: 0 ok, 1 API or sign-in error, 2 usage error.

Shell completion

Load the completion script when your shell starts.

Shell	Add this line	To
zsh	`source <(asteroid complete zsh)`, after `compinit`	`~/.zshrc`
bash	`source <(asteroid complete bash)`	`~/.bashrc`
fish	`asteroid complete fish \| source`	`~/.config/fish/config.fish`
PowerShell	`asteroid complete powershell \| Out-String \| Invoke-Expression`	`$PROFILE`

Environment

Variable	Use
`ASTEROID_API_KEY`	Authenticate with an API key instead of `asteroid login`.
`ASTEROID_API_URL`	API host. Defaults to `https://odyssey.asteroid.ai`.
`ASTEROID_ORG`	Default organization, by id or name.
`ASTEROID_CONFIG_DIR`	Where the CLI keeps its config and, without a keychain, its sign-in.
`ASTEROID_NO_BROWSER`	Print the sign-in link without opening a browser.
`ASTEROID_NO_KEYCHAIN`	Store the sign-in in a private file, not the OS keychain.

CLI reference

Every command, its arguments and its flags

Call a workflow

Run workflows from your own code

Get Started

Reference

Organizations

CI and agents

Shell completion

Environment

Next

CLI reference

Call a workflow

​Organizations

​CI and agents

​Shell completion

​Environment

​Next

CLI reference

Call a workflow

Organizations

CI and agents

Shell completion

Environment

Next