CLI reference - Albus Documentation

The CLI is a thin shell over the Python SDK: each command that calls Albus maps to one API operation and prints the JSON response on stdout, so output pipes into jq. --help on any command lists its options.

albus sessions get my-session | jq '.messages[-1].content'

Commands

Command	API operation	Notes
`albus login [--no-browser]`	—	Browser sign-in; `--no-browser` prints the URL and waits
`albus logout`	—	Forget the stored session
`albus whoami`	`GET /whoami`	Names what the credential in effect authenticates: `user` or `api_key`
`albus status`	`GET /whoami`	JSON: `cli_version`, `base_url`, `credential`, `authenticated`, `caller` or `error`; exits `0` either way
`albus health`	`GET /health`
`albus sessions run ID -p TEXT --agent-name NAME …`	`POST /sessions/{id}`	Options below; prints the response plus `invocation_key`
`albus sessions list`	`GET /sessions`
`albus sessions get ID [--after C] [--limit N]`	`GET /sessions/{id}`	The conversation; limit defaults to 100
`albus sessions audit ID [--after C] [--limit N]`	`GET /sessions/{id}/audit`	The audit log
`albus sessions delete ID`	`DELETE /sessions/{id}`
`albus agents list`	`GET /agents`
`albus agents get NAME`	`GET /agents/{name}`	Current configuration plus every revision
`albus agents revision NAME REVISION`	`GET /agents/{name}/revisions/{revision}`	One revision’s configuration
`albus models list`	`GET /models`	The models Albus serves, and the provider of each
`albus secrets list`	`GET /secrets`
`albus secrets create NAME [--value V]`	`POST /secrets`	Omit `--value` to read stdin
`albus secrets get NAME`	`GET /secrets/{name}`	Masked
`albus secrets update NAME [--value V]`	`PUT /secrets/{name}`	Rotation; no configuration change
`albus secrets delete NAME`	`DELETE /secrets/{name}`
`albus tokens list`	`GET /tokens`	Browser session only
`albus tokens create NAME`	`POST /tokens`	Prints the only copy of the key
`albus tokens get ID`	`GET /tokens/{id}`
`albus tokens delete ID`	`DELETE /tokens/{id}`
`albus invites create EMAIL`	`POST /invites`	Browser session only
`albus traces list [--agent-name NAME] [--agent-revision REV] [--status S] [--session ID] [--since T] [--until T]`	`GET /traces`
`albus traces get INVOCATION_KEY [--attempts final\|all]`	`GET /traces/{invocation_key}`

Memories have no CLI commands yet — read them over HTTP, from the SDKs, or in the console.

`sessions run` options

Option	Meaning
`--prompt`, `-p`	The user prompt. Required.
`--agent-name`	Name identifying the agent. Required.
`--model`	Model identifier. Required unless `--agent-file` is given.
`--provider` / `--credential`	Your own provider and its secret reference. Must be given together.
`--system-prompt`	System instructions.
`--tool`	A built-in tool — `web_search` or `terminal`. Repeat to allow several.
`--max-steps`	Cap on model steps.
`--agent-file`	JSON file holding the whole agent configuration. Cannot be combined with the options above.
`--invocation-key`	Names the invocation; the `Idempotency-Key` header over HTTP.
`--wait` / `--no-wait`	Block for the reply (default) or return once accepted (`wait_timeout_seconds=0`).
`--wait-timeout`	Seconds to block server-side, up to `1800`. Omit for the 30-minute maximum.

Global options

Option	Meaning
`--base-url`	API base URL. Overrides `ALBUS_BASE_URL`; defaults to `https://albus.sh/api`.
`--timeout`	Per-request timeout in seconds (default 30). A waiting `sessions run` is exempt.
`--version`	Print the CLI version.

Environment

Variable	Read by	Meaning
`ALBUS_API_KEY`	CLI, SDKs	Organization API key. In the CLI it wins over a stored session, except for `tokens` and `invites`.
`ALBUS_BASE_URL`	CLI	Default API base URL. Credentials are stored per base URL.
`ALBUS_CONFIG_DIR`	CLI	Where the browser session is stored. Falls back to `$XDG_CONFIG_HOME/albus`, then `~/.config/albus`.
`ALBUS_BEARER_AUTH`	SDKs	User bearer token, when the client is constructed with no credential.

Exit codes

0 on success, 1 on any failure. A failure prints two lines on stderr and no traceback:

albus: <what the server or the client refused>
albus: docs: https://docs.albus.sh/guides/troubleshooting

albus status is the exception: it exits 0 even when the credential is rejected, and reports the refusal in its JSON error field.