albus CLI

Command-line client for the Albus REST API, built on the public albus-sdk Python SDK. It is a thin shell over the SDK: every command that calls Albus maps to one API operation and prints the JSON response, so output pipes into jq.

Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.ps1 | iex

Pin a version:

curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | ALBUS_CLI_VERSION=0.2.0 sh

The installer uses, in order: uv tool install, pip install --user, or pip inside a conda environment. It does not download OS-specific binaries. To install directly instead:

uv tool install albus-cli
# or
pip install --user albus-cli

Authentication

Sign in with a browser, which stores a session per base URL and renews it as it expires:

albus login
albus whoami
albus logout

albus health is the one command that needs no credential, matching its empty security in api/openapi.yaml: run it first to tell an unreachable API from an unauthenticated one. albus status reports which credential is in effect and whether Albus accepts it, as JSON, exiting 0 either way — it is the one command to run to find out where you stand. albus login --no-browser prints the authorization URL instead of opening it, for a coding agent signing in the user in front of it.

Or export an organization API key, which wins over a stored session so CI and agent harnesses need not touch disk:

export ALBUS_API_KEY=...     # organization API key
export ALBUS_BASE_URL=http://localhost:8080/api/v1  # optional; defaults to prod

--base-url overrides ALBUS_BASE_URL, and --timeout bounds each request (a waiting sessions run long-polls and is exempt). A user who belongs to several organizations acts in the one joined first; --org <organization id> (or ALBUS_ORG) selects another, and albus whoami lists them under organizations with the selected one as active_organization. An API key is bound to its organization and ignores --org.

albus login opens a browser on this machine and listens on 127.0.0.1:8484-8487; on a headless host, forward those ports or export ALBUS_API_KEY instead. The session is written to $ALBUS_CONFIG_DIR/credentials.json, else $XDG_CONFIG_HOME/albus/credentials.json, else ~/.config/albus/.

Operations whose security in api/openapi.yaml lists bearerAuth only, such as /tokens and /invites, need the browser session. albus tokens and albus invites use it even when ALBUS_API_KEY is exported, and say to run albus login when there is none. Sign in first, then albus tokens create to mint the key that ALBUS_API_KEY carries.

albus whoami takes either credential and names the caller it authenticates: the signed-in user with the organizations they belong to, or the API key with the organization it acts in.

Commands

albus health
albus --version
albus login
albus login --no-browser
albus whoami
albus logout
albus status

albus sessions run my-session -p "summarize the incident" \
  --agent-name support-triage --model gemini-3.6-flash \
  --provider google_agent_studio --credential albus.sh/secrets/gemini-key
albus sessions run my-session -p "and the follow-up?" \
  --agent-name support-triage --agent-file agent.json --no-wait
albus sessions list
albus sessions get my-session --limit 20
albus sessions audit my-session --after "$cursor"
albus sessions cancel my-session
albus sessions delete my-session

albus traces list --agent-name support-triage --status FAILED
albus traces get "$invocation_key" --no-payloads --attempts all

albus secrets list
albus secrets create gemini-key --value ...   # or pipe the value on stdin
albus secrets get gemini-key
albus secrets update gemini-key < value.txt
albus secrets delete gemini-key

albus agents list
albus agents get support-triage
albus agents revision support-triage "$revision"

albus tokens list
albus tokens create ci
albus tokens get "$id"
albus tokens delete "$id"

albus invites list
albus invites create teammate@example.com
albus invites revoke "$id"

albus organization get
albus organization rename "Albus Labs"
albus organization members
albus organization set-role "$user_id" admin
albus organization remove-member "$user_id"

albus billing balance
albus billing ledger --after "$cursor"
albus billing checkout 20 --success-url https://... --cancel-url https://...

albus models list

albus memories groups
albus memories list --group team-a
albus memories delete "$id" --group team-a
albus memories delete-group --group team-a

memories groups lists the organization's memory groups with their active counts; memories list --group reads one group's memories, newest first. Both page with --after and --limit.

models list gives the model names sessions run --model takes, each with the provider it runs on — which is the provider the --credential secret has to be for.

tokens create prints the only copy of the key value the API ever returns; list and get return metadata alone.

invites create invites a person by email to join your active organization, as a member unless --role admin says otherwise. invites list and invites revoke, like the organization member commands, need the admin role.

billing checkout starts a credit purchase and prints the payment page URL to send the buyer to; like tokens and invites, it needs albus login rather than an API key. billing balance and billing ledger take either.

traces list searches the last 31 days of invocations unless --since and --until say otherwise; traces get reads one with a page of its spans, and --no-payloads returns the shape without what each span was given and produced.

sessions run waits for the assistant response by default; pass --no-wait to return as soon as the invocation is accepted, or --wait-timeout to bound the wait server-side. The response carries message once the invocation has answered, and omits it otherwise — with --no-wait, or when the wait ended first; albus sessions get reads the message later.

Pass --invocation-key to name the invocation and make the run retry-safe. The JSON output carries the effective invocation_key, whether supplied by the caller or generated by the server — absent only if something between the CLI and Albus strips the response header on a run that supplied no key.

--agent-file takes a JSON object shaped like the API's AgentConfig and covers what the flags do not (MCP servers, provider URL overrides):

{
  "model": { "name": "gemini-3.6-flash" },
  "mcp_servers": [
    { "name": "github", "url": "https://mcp.example.com/mcp" }
  ]
}

Documentation

The CLI prints both, so whoever is reading its output has the URL that is theirs.

Development

The CLI is developed in the private Albus repository, next to the api/openapi.yaml contract and the SDK it is built on, and each release is copied to the public albusgroup/albus-cli repository. That repository accepts issues, not pull requests — see CONTRIBUTING.md.

make check      # ruff, mypy --strict, pytest