CLI reference
Edit on GitHubGlobal flagsSessions and runsThe nodeOrrery CloudProviders, models, profilesConfiguration and trustExtensionsRegistry (administrators)Records, workflows, evalsSlash commandsExit codes
orrery --help is the map, and every subcommand has its own --help. With no subcommand, orrery starts an interactive session.
Global flags
These work on every subcommand.
| Flag | Meaning |
|---|---|
--profile <name> | Which profile to resolve. |
--workspace <path> | The workspace root. Defaults to the current directory. |
--ui <id> | Which client renders. |
--json | Shorthand for --ui json: AG-UI events as JSON lines on stdout. |
--consent <once|always|never> | What an ask rule does. |
-v | Log level on stderr. Repeatable. |
--provider <id>:<model>[@<url>] | The model for this run. fixture:<file> repeats, one per model pass. --provider ? lists the ids. |
--state-dir <path> | Where sessions are stored. Defaults to <workspace>/.orrery. |
--continue | Continue this workspace's latest session. |
--resume <id> | Continue this session (an unambiguous prefix works). |
--max-turns <n> | Stop the main agent after n model passes in a run. |
--budget <usd> | Stop the main agent once a run has cost this much. |
Sessions and runs
| Command | Does |
|---|---|
orrery run -p <prompt> [--attach <path>]… | One turn, print the final text, exit. A prompt that starts /mcp.<server>.<prompt> is filled in by that MCP server first. With --json, an extension's notice is CUSTOM orrery.notice. |
orrery serve [--listen <addr>] | Start a kernel, print its endpoints, keep running. |
orrery attach [<target>] [--token <t>] [--since <seq>] [-p <prompt>] | Attach to a running kernel. |
orrery replay <session> | Re-emit a stored session as events. |
orrery session list | List stored sessions. |
orrery session show <id> [--agent <name>] | Show one session, or a sub-agent's thread. |
orrery session rm <id> [--yes] | Delete one session. |
The node
| Command | Does |
|---|---|
orrery node up [--install] [--listen <addr>] | Start this machine's node in the background. |
orrery node down [--uninstall] | Stop it. |
orrery node status | Whether it runs, where, and its sessions. Exits 1 when no node runs. |
orrery node token [--name <name>] | Issue a token for a client on another machine. |
orrery node run [--listen <addr>] | Run the node in the foreground. |
orrery node join [<relay>] [--cloud <url>] [--name <name>] [--env-file <path>] [--force] [--no-autostart] | Enrol this machine with Orrery Cloud through a relay, once: joined already prints already joined as <name> and exits 0 (--json: {"already": true}). --force pairs again as a new machine. It installs the autostart unless --no-autostart. See Orrery Cloud. |
Orrery Cloud
| Command | Does |
|---|---|
orrery login <relay> [--cloud <url>] [--name <name>] | Sign this terminal in with a device code. |
orrery logout | Forget this terminal's sign-in. |
orrery machines | Your machines, and whether each is online. |
orrery sessions | The sessions on your machines. |
orrery handoff <session> --to <machine> [--include-untracked | --skip-untracked] | Move a session to another machine, with its uncommitted work. |
Providers, models, profiles
| Command | Does |
|---|---|
orrery providers [list] | Every provider kind and every setup. |
orrery providers add <kind> [flags] | Set one up. See Providers and models. |
orrery providers remove <name> | Forget a setup and its sign-in. |
orrery providers status [<name>] | Whether each setup has a key. Exits 5 when one needs one. |
orrery models | Every model your setups serve. |
orrery models add <provider> <model> [--use] | Add a model id to a setup. |
orrery profile list | Every profile, default first. |
orrery profile show <name> | One profile, env values masked. |
Configuration and trust
| Command | Does |
|---|---|
orrery config explain <key> | Where a key's value came from. |
orrery config set <key> <value> [--layer user|workspace] | Write one key. |
orrery config unset <key> [--layer user|workspace] | Remove one key. |
orrery init [--profile <name>] | Write a starter .orrery/config.toml. |
orrery import [--from <harness>] | Import configuration from another harness. |
orrery trust grant [<path>] | Trust a workspace. |
orrery trust revoke [<path>] | Forget the answer for a workspace. |
orrery trust list | Every stored answer. |
orrery permissions explain <call> [--subject <s>] | Which rule decides a call. |
Extensions
| Command | Does |
|---|---|
orrery install <source> [--to user|workspace] [--user] [--link] [--yes] [--force] [--index <path>] | Install an extension. |
orrery remove <name> [--from user|workspace] [--user] | Remove one. One of Orrery's own (git, builtin, a provider…) is turned off with [extensions.<id>] enabled = false instead, its folder kept; orrery install <id> turns it back on. ratatui is refused. |
orrery ext list [--watch] [--json] | Every extension in ~/.orrery/extensions and the project's .orrery/extensions: ID, FROM, RUNTIME, STATE, PID, MEM, CPU, UP, RESTARTS, RESIDENT (from 90 columns; --json always has it), and a totals line. Under 90 columns, CPU, UP and RESIDENT are dropped. A copy hidden by the project's is listed as shadowed under it. --watch redraws every second. |
orrery ext ps [--watch] [--json] | One row per running process, the kernel first (with orrery node up). |
orrery ext show <name> | Its folder, the copy it shadows, and what it registered. |
orrery ext test [<name|path>] | Run an extension's tests against the mock broker. |
orrery client new --from ratatui|ink <name> | Scaffold your own client in ./<name>: a Cargo project on the ratatui client library (ratatui) or a pnpm project on @getorrery/client-ink (ink), with one example component, its orrery.toml and a README (Build your own client). Refused when the folder exists, or when the name is not lowercase letters, digits and dashes. |
orrery ui preview <component> [--name <name>] [--data <file>] [--width <n>] [--mono] [--fixture <file>] [--now <ms>] | Draw a component headless, as the TUI draws it, and print it (Preview a component). <component> is a structure JSON file, <ext>.<name> from an installed extension, or an orrery.toml with --name. Checks it as the host does (structure, schema with its defaults, binding, actions); a mistake exits 2 naming the path and the fix, a pointer that resolves to nothing is a warning and exits 0. --width 20 to 500, default 80. --fixture also writes a conformance scenario. --now sets "now" for relative and date. Limits: a bare structure file has no schema or action check; the size limits are not checked; colour is ANSI-16, plain text in a pipe or with NO_COLOR; nothing is focused or interactive. |
orrery publish [<path>] [--dry-run] | Ask for a verified listing: check, test, hash the published version, open a pull request to the public index. |
orrery mcp list | Declared MCP servers. Starts nothing. |
orrery mcp tools <server> | Connect to one and list its tools. |
orrery mcp login <server> | Sign in to a server declared with oauth = true: opens the authorization page, catches the answer on a local port, and keeps the token outside the config. |
orrery skills list [--agent <name>] | Discovered skills. |
orrery skills show <name> | One skill. |
Registry (administrators)
| Command | Does |
|---|---|
orrery registry init --index <path> [--key <path>] [--key-id <id>] [--expires <instant>] | Make a signing key and an empty index. |
orrery registry add --index <path> --id <id> --version <v> --source <src> | Pin one version. src is crates-io:<name>, npm:<name> or url:<url>. |
orrery registry sign --index <path> --key <path> | Sign every pin, then the document. |
orrery registry verify --index <path> [--key <hex>] | Check an index the way an install does. |
Records, workflows, evals
| Command | Does |
|---|---|
orrery ledger [--session <id>] [--subject <s>] [--rule <r>] [--stream load|audit|telemetry] [-n <n>] | What was decided, and by which rule. |
orrery telemetry [--session <id>] [-n <n>] | Model requests and routing decisions. |
orrery workflow check <file> | Typecheck a workflow. Starts no kernel. |
orrery workflow run <file> [--max-tokens <n>] | Run one. |
orrery eval run <suite> [--profile <a,b>] [--model <a,b>] [--format <f>] | Run an evaluation suite. |
orrery eval compare <run-a> <run-b> | Compare two runs. |
orrery eval replay <run> --case <id> | Re-open one case. |
Slash commands
Typed in a session; The TUI lists them all.
| Command | What it does |
|---|---|
/ext restart <id> | Stops the extension's process, forgets its crashes and starts it again. What it placed, marked stopped, is live again. /ext alone prints the usage. |
Limits
- Only a process extension loaded in this session: a linked one runs in the harness and has no process, and an unknown id is refused, naming
orrery ext list. - If it crashes again while starting, the reply says why and the surfaces stay
stopped;orrery ext show <id>has its output. restartis the only subcommand.- Down a pipe (
orrery run -p) slash commands are not run: restart from a session (the TUI, orserve+attach).
The ones that write configuration:
| Command | What it does |
|---|---|
/ui | Lists what is placed now: id, placement (inline, footer, band, pane.left, pane.right, hidden), owner (ext:<id>, agent, config) and state (live, loading, stopped). |
/ui move <id> <placement> | Writes [ui.placements."<id>"] placement = "<placement>" to the user config.toml, and moves it in this session at once. |
/ui hide <id> | The same with placement = "hidden". |
/ui save <id> | Writes where <id> is now, so the next session places it there too. |
Writing the key by hand does the same from the next session on (decision 0003).
Limits
- Text subcommands only: the
m,handskeys of the designed list are not built yet. - An id is a config key per id, not per owner: two owners using the same id both move.
- An id holding a
"cannot be written, and is refused with that reason. saveneeds the id placed now;moveandhidetake an id that is not placed yet.- The move in this session lasts until the session ends; the key is what persists. Remove the key (
orrery config unset 'ui.placements."<id>".placement') to give the owner its choice back. - Closing one surface for this session only (dismiss) is not a
/uisubcommand.
Exit codes
0 ok · 1 task failed · 2 usage · 3 budget · 4 denied · 5 needs a key or sign-in · 6 kernel or transport failure.