AsteroidsCLI reference
ast — agents like fly.io apps
npm i -g @asteroidbelt/ast. The CLI speaks only the public API, so everything it does the raw API can do too.
auth
| command | what it does |
|---|---|
ast auth login | opens the browser to authorize this machine; mints a personal token (read+write) |
ast auth login --no-browser | prints a URL to open anywhere; polls until approved (headless/CI bootstrap) |
ast auth whoami | who the current token acts as, resolved universe, scopes |
ast auth logout | forgets the stored token (revoke it in Settings → API tokens) |
Config lives at ~/.config/ast/config.json. CI needs no login or config — set AST_API_TOKEN (and optionally AST_API_URL).
launch / deploy
| command | what it does |
|---|---|
ast launch | scaffolds ./agent.toml if absent, creates the agent from it, stamps the slug back into the file |
ast deploy | re-applies ./agent.toml to the existing agent (prompt + settings; idempotent) |
agent
| command | what it does |
|---|---|
ast agent create [--type --llm --name] [-f file] | flags-only create; bare create = the instant default |
ast agent list · show <slug> | agents in the current universe |
ast agent message <slug> "…" [--detach] | send one message and stream the turn until idle |
ast agent chat <slug> | interactive REPL over the standing stream |
ast agent interrupt <slug> | abort the in-flight turn |
ast agent logs <slug> [-f] [--since 1h] | pod logs; -f follows live |
ast agent destroy <slug> | tear down the pod and delete the agent (admin scope) |
universe / secrets
| command | what it does |
|---|---|
ast universe list · create <slug> · switch <slug> · show | grouping boundary; switch scopes every later command |
ast secrets set <slug> KEY=VALUE … | set values for keys declared in the spec (write-only) |
ast secrets list <slug> · unset <slug> KEY | set/unset status; values never come back |
A full session
bash
$ npm i -g @asteroidbelt/ast
$ ast auth login
Logged in as dev@example.com (universe: dev-3f2a)
$ ast launch
Scaffolded agent.toml — edit it anytime; re-apply with `ast deploy`.
Launched research-agent (hermes · deepseek-v4-pro)
$ ast agent message research-agent "What can you do?"
I'm a persistent research agent — give me a topic and I'll dig in.
$ ast secrets set research-agent NOTION_TOKEN=secret_…
set NOTION_TOKEN