CLI reference

Everything Arcturn accepts, in one place. The pages linked from each entry are where the reasoning lives; this is the index you come back to when you know the feature exists and want the exact spelling.

Invocation#

arcturn                              # interactive TUI in the current directory
arcturn "fix the flaky retry test"   # TUI, seeded with a first prompt
arcturn -p "summarise src/auth.ts"   # run once, print the answer, exit
cat notes.md | arcturn -p            # piped stdin becomes the prompt
cat ctx.txt | arcturn -p "explain"   # piped stdin becomes leading context

With -p and a prompt argument, Arcturn waits briefly for piped input and then proceeds without it. That matters when a parent process — CI, a Makefile, subprocess.run — leaves an inherited stdin open that never closes; waiting for EOF there would hang forever.

Flags#

--host, --port and --token apply to arcturn serve; --cassette applies to arcturn bisect, and --record <file> on any run writes the cassette it reads.

--max-cost and --max-turns are the two worth reaching for by default. An agent that loops on a failure it cannot fix spends real money doing it, and a ceiling turns "I checked my bill on Friday" into "the run stopped."

--max-cost can only fire for a model that publishes pricing — a cost Arcturn cannot compute is a cost it cannot compare. Point --max-cost at an unpriced endpoint (Ollama, vLLM, an in-house gateway, anything registered by an extension without a cost) and Arcturn says so at startup rather than letting you believe you are protected; bound those runs with --max-turns instead.

Exit codes#

The same table is in arcturn --help.

Subcommands#

arcturn add never links a package's executable code without being told to. A package carrying extensions/ stops for a per-install confirmation that names the files, and off a TTY — CI, a pipe, a script — it declines rather than assuming consent. --yes is how you grant that consent up front, and --skills-only is how you take the package's markdown and leave its code on disk unlinked. arcturn inspect is the same resolver with the linking taken out: it prints the agent lanes, workflow budgets and executable files an install would add, and adds none of them — run it before you reach for --yes.

A bare name — arcturn add starter-skills, arcturn inspect starter-skills — is looked up in the hub's index.json first, printed as resolving "starter-skills" via the hub → …, and then handled exactly as if you had typed the source it resolved to: same resolver, same confirmation, same --yes. arcturn search [query] lists what is there to be named.

Slash commands#

Typed inside the interactive TUI.

Session and context#

/rewind restores files and forks the conversation, rather than truncating it. The session is a tree, so the branch you rewound away from is still there.

Models, cost and appearance#

Changes#

These three are the dry-run loop: with --dry-run, edits land in a shadow copy until you have read them.

Packages#

The same four operations as arcturn add|packages|remove|update, against the same ~/.arcturn/packages and the same fail-closed confirmation for executable code. The shell verbs exist so an install can happen in CI or a setup script; the slash commands exist so it can happen without leaving a session.

Delegation#

The distinction between /bg, /team, /scout and /workflow is what each is for: /bg is one task off-thread, /team is several agents on one goal with a merge step, /scout is competing approaches you pick between, and /workflow is a scripted pipeline whose shape you decided in advance. Teams compares the first three; Workflows covers the last.

/org memory entries are inert until a person approves them — a proposed entry is never injected into a role's prompt. That gate exists because a memory entry becomes standing instruction text in later runs, which is not something a model should be able to grant itself.

That gate is why arcturn serve exposes /org memory in three parts and not four: a remote client can read the store, propose an entry and revoke or delete one, and there is no verb that approves. An engine cannot tell a frame a person clicked from a frame an agent sent, and add is live precisely because you typed it. /bg is reachable in full; /team and /scout are not reachable at all. See Server mode and Teams.

Related#

• Getting started — installation and first run
• Packages — what add, inspect, update and remove install, and the gate that stands in front of executable code
• Configuration — everything settable in .arcturn/config.json
• Model providers — every backend, credentials, and which are verified live
• Permissions — what each --permission-mode actually grants