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/.
After any command, albus notes on stderr when PyPI has a newer release. It
asks at most once a day and caches the answer in the same directory; set
ALBUS_NO_UPGRADE_CHECK=1 to switch the check off.
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_ai_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
| Reader | URL |
|---|---|
| A person | https://docs.albus.sh |
| A coding agent | https://docs.albus.sh/agents/docs.md |
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
Metadata
Release files for albus-cli 0.12.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| albus_cli-0.12.2.tar.gz | 103.3 kB | Without provenance | Details for albus_cli-0.12.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| albus_cli-0.12.2-py3-none-any.whl | Python 3 | none | any | Details for albus_cli-0.12.2-py3-none-any.whl |
Total release size: 144.5 kB
Release files / albus_cli-0.12.2.tar.gz
| Download URL | albus_cli-0.12.2.tar.gz |
|---|---|
| Size | 103.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ddfb3e15d1549697841464717e73a3194d3b1c15dbeb46ac0449b27da711285e
|
|
BLAKE2b-256 checksum How to use checksums |
b3ab3f2c5b576626700b4b1613cc7b274711e74c92199320d8172017824785fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / albus_cli-0.12.2-py3-none-any.whl
| Download URL | albus_cli-0.12.2-py3-none-any.whl |
|---|---|
| Size | 41.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad1a0bab856dc63ab96fe9d1da1298d92a739a03c0761b471f814a099cbfa883
|
|
BLAKE2b-256 checksum How to use checksums |
5fd3e6e4462b395bdc49f8c5dae38aeeb39aa5760f1eac4383b91133bfe25bad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for albus-cli 0.12.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.