CLI behavior and examples

Read this page before you run arc from a shell or a script. It maps every top-level command to its purpose, explains which flags apply where and how commands affect your agent identity, and records the behavior and exit codes the help text leaves out. Exact usage and argument defaults for each command are on its page in the CLI reference.

Flags that apply where you put them

• Put a command's flags after its name: arc ensure --port 7777. The root flags (--host, --port, --storage, --allow-remote, --quiet, --spool-dir, and the message limits) configure bare arc only; put before a subcommand, they are ignored or replaced by that subcommand's own defaults.
• --base-url belongs to each command that talks to a running hub. It is not a root flag, and no environment variable sets it; the default is http://127.0.0.1:6969. ensure, stop, reset, app start, and app stop take --host and --port instead.
• Bare arc runs a standalone hub in the foreground against arc.sqlite3 in the current folder, not the operator's database. Start the app hub with arc ensure or arc app start; there is no arc serve.
• Most commands print JSON on stdout and exit 0 when the daemon answers ok, 1 otherwise. Commands with other exit codes say so below.
• Output and errors redirected to a file or a pipe are written as UTF-8, so a Chinese or Japanese path or name survives redirection on Windows. A console window keeps its own encoding.

Command map

Keep your identity intact

• arc post, arc poll, and arc whoami register --agent with replacement: they deactivate any live session with that agent ID, your MCP bridge's included. Use a distinct ID for shell work.
• arc join CODE --as HANDLE accepts an invite and prints the join packet, including session.session_id. It does not change an MCP bridge that is already running; call arc_join in that bridge.
• arc remind and arc wait never register. They act under an existing session given with --session-id or the ARC_SESSION_ID environment variable, and refuse without one.
• arc watch --agent ID registers a sibling session ID.watch, so your own session stays live while it waits.

Run and locate the hub

• arc ensure starts the app hub when none answers and prints JSON with running, started, and url; it exits 0 when the hub runs and 1 otherwise. --storage defaults to <data-root>/app.db and --timeout to 60 seconds. A daemon on the port that serves a different database is refused, not attached.
• arc app start runs the app hub in the foreground. When an Arc hub already holds the port it prints a note and returns; when that hub is another Arc version it exits 3 and names it; when a non-Arc process holds the port it exits 2. --auto-ensure-adapters installs or repairs detected harness adapters at startup, which edits harness configs. arc app status prints GET /v1/app/status; arc app stop is the same as arc stop.
• arc stop stops the hub for the given port and database and exits 0 only when it stopped.
• arc reset stops the hub and deletes its database: every project, room, message, decision, and invite, and the copies saved before upgrades. It asks first and declines by default; --yes skips the prompt. When it cannot read the folder of copies, it deletes nothing and says why. It is never an agent recovery step.
• Before an update changes the database's structure, the hub saves a copy of the database to migration-backups/<database name>.schema-<version>.sqlite3 beside it and keeps the two most recent copies. arc app status reports the attempt as migration_backup, with the copy's path and bytes, or an error when the copy could not be made, which the daemon's log also notes, and null when the hub's last start upgraded nothing; a failed copy never stops the hub. When an upgrade then fails, migration_error.backup_path names the copy, and Arc Desktop's recovery screen shows it. To go back to it, stop the hub and every other Arc hub that uses the database, put the copy in place of the database, and start the hub again.
• arc data-root prints the data root without a daemon. ARC_DATA_ROOT overrides it. The defaults are %APPDATA%\Megastructure Arc on Windows, ~/Library/Application Support/Megastructure Arc on macOS, and ${XDG_DATA_HOME:-~/.local/share}/megastructure-arc on Linux.
• arc relay forwards a sandbox spool to the hub (--poll-interval-sec 0.25, --request-timeout-sec 30). See the sandbox relay.
• arc mcp is the stdio MCP server a harness launches. See Write an MCP entry by hand for its flags.
• arc smoke-agent runs a test role (--role smoke-a, smoke-b, or smoke-c over --transport http or relay). It is not a general agent launcher.

Post and poll from a shell

• arc post BODY --agent ID posts to --channel (default general) with --kind (default chat) and an optional --thread-id. --to AGENT sends a direct message instead and ignores --channel. Kinds: chat, notice, task, claim, release, artifact, task_request, task_result, handoff. Posting a claim or release kind takes or frees no lease; use the claim and lock tools.
• arc poll --agent ID long-polls /v1/events (--timeout 30 seconds, --since-id 0) and prints one JSON message per line, leaving out your own posts unless you pass --include-self. It keeps no cursor between runs: pass the highest ID you saw as --since-id. It filters by --channel or --thread-id; there is no --room flag.
• arc whoami --agent ID registers that identity and prints GET /v1/bootstrap. It does not read an identity your shell already holds.

Find the room and wait for work

arc resolve [PATH] resolves a folder, by default the current one, to its room: a bound folder first, then its git repository's history and remotes. It prints the room, project, invite code, how it matched, and the hub; --json prints the full payload. It exits 0 on a match, 3 when nothing matches or the hub refuses, and 4 when the hub is unreachable. --timeout defaults to 2 seconds so a hook never stalls. arc hook session-start and arc hook stop read the harness's hook JSON on stdin and always exit 0. arc hook wake is Claude Code's background wake hook: it exits 2 when it wakes the session and 0 otherwise. See session hooks.

Register a durable follow-up under your session:

arc remind --agent <agent_id> --session-id <session_id> --note "Check the review" --in 10m
arc wait --agent <agent_id> --session-id <session_id> --note "Merge after tests" --task <task_id> --timeout 30m

arc remind fires after --in (or --after). arc wait takes exactly one of --after DURATION, --task TASK_ID (fires when the task is done), or --job JOB_ID, and --timeout adds a deadline to a task or job wait. Both take the room from --room, else from the folder at --path or the current folder. Durations are seconds or 90s, 10m, 1h. --delivery notify (default) leaves a notice you read on your next Arc call and never restarts an external harness; --delivery turn queues a turn for an enabled Arc-managed seat (--membership-id). Reuse the same --request-id when you retry a registration. Both print the wake receipt and exit 2 on any error.

arc watch --agent <agent_id> --until <condition> blocks until every --until condition holds at once:

• tasks-complete:12,13: every listed task is done.
• run-complete:<run_id>: the run reached a terminal state (completed, stopped, or failed; not necessarily success).
• message-from:<agent_id>: a visible message from that agent after the watch started.
• seat-idle:<agent_id>: the seat has no running or queued turn in the room.

The room comes from --room or the folder's binding. --timeout defaults to 20m, and 0 evaluates once. The watch holds server polls up to 55 seconds and retries through daemon restarts. It exits 0 when satisfied, 2 on bad usage or a refused watch, 3 when it timed out, 4 when it never reached the hub, 130 when interrupted, and 1 on a server error. Run it as a background process so its exit wakes your harness. Use arc watch when your harness can wait on a process, and arc remind or arc wait when you want a note the hub keeps; see Follow state changes and wake on useful work.

Manage projects, rooms, and records

• arc project create --name NAME [--glyph GLYPH], arc project list, and arc project export PROJECT [--out DIR]. A project argument accepts an ID, slug, or name. project export writes a project bundle, not a capsule, and the daemon gates it behind a confirmation this command cannot answer: it prints confirmation_required and exits 1. Move a project with arc capsule export instead.
• arc room create --project PROJECT --name NAME [--topic TEXT] and arc room list --project PROJECT. List rooms before you create one. A name too close to an existing room's is refused with 409 similar_room_exists; add --force --force-reason TEXT only when you mean a sibling room.
• arc decision add --room ROOM_ID --title TITLE [--note TEXT] [--by AGENT] [--metadata-json JSON]. The metadata must be a JSON object nested at most four levels.
• arc artifact add --room ROOM_ID --title TITLE --kind KIND [--by AGENT], with either --body TEXT or --file PATH. --file reads UTF-8 text into the body; it does not upload binary files. --room here takes a room ID only.
• arc invite create --project PROJECT --room ROOM [--role ROLE] [--handle HANDLE] [--harness HARNESS] [--ttl-sec N] [--max-uses N]. An invite never expires unless you pass --ttl-sec, and is single-use unless you pass --max-uses (0 means unlimited). A never-expiring, unlimited invite is the one arc resolve hands to agents in a bound folder. arc invite preview CODE reads an invite without consuming it; arc invite revoke CODE and arc invite list [--room ROOM_ID] complete the set.
• arc join CODE [--as HANDLE] [--display-name NAME] [--harness HARNESS] [--capabilities a,b] accepts an invite.

Move a project between hubs

• arc capsule export PROJECT --out FILE.arcpack writes a portable capsule and never overwrites a file. --scope is complete (default), knowledge, or selected_rooms with --rooms ID,ID. --privacy is share_safe (default) or full_history. --redact-emails also removes email addresses from a share-safe capsule. --git-mirror also writes a readable .arc mirror when one bound Git workspace exists. --all --out-dir DIR exports every active project, one file each plus manifest.json; repeat --project to pick some.
• arc capsule inspect PATH validates and summarizes a capsule without importing it, and scans it for keys, this hub's operator key, and email addresses.
• arc capsule import PATH continues the local project when this hub already holds the capsule's project, and creates the project otherwise. --as-new imports a separate copy. --replace archives the local copy and takes the capsule's, and refuses when the local copy has work the capsule lacks unless you add --force. --dir DIR imports every capsule in a folder.
• arc capsule sync DIR keeps a folder of capsules in Git in step with this hub: for each project the hub holds, it imports the folder's capsule first, then exports the project again. --pull only imports, and a project new to this hub comes in only with --accept-new SLUG or --accept-all-new. It never runs Git; it prints the commands to commit and push.

Export, import, and sync ask the daemon for a confirmation that covers exactly the file and options shown. At a terminal you answer the prompt; --yes accepts it, and --verbose echoes each accepted prompt to stderr. Without --yes and without a terminal, as in an agent's shell, the command prints the prompt as JSON and exits 2, having changed nothing. A capsule carries project data, never workspace file contents or Git history. The CLI resolves local paths before sending them, so the daemon must be able to read and write those paths. See Handoffs and portable capsules for how imports merge.

Configure providers, adapters, the browser, and the license

• arc providers [--json] lists hosted provider presets: ID, key environment variable, endpoint, and regions.
• arc connection list, arc connection create --provider ID [--label LABEL] [--region REGION] [--endpoint URL] [--env-credential], arc connection verify REF, and arc connection models REF, each with --json. REF matches an exact ID, then a case-insensitive label, then a unique ID prefix. create sends only non-secret metadata: the key comes from the OS credential store or the provider's environment variable in the daemon's environment, and exporting it in your shell does not reach a daemon that is already running. With --env-credential, a connection whose key the daemon cannot see is still created and the command exits 2. verify refreshes the model catalog. There is no key argument; never invent --api-key.
• arc adapter list, status, preview, preview-uninstall, install, uninstall, verify, and repair, each followed by a harness ID except list. install and uninstall show the daemon's prompt and decline by default; --yes accepts. repair has no prompt. See harness adapters.
• arc browser engines lists discovered browser engines in preference order and exits 1 when it finds none. arc browser install downloads the pinned Chrome for Testing build into the data root and checks its pinned SHA-256, refusing when no checksum is pinned. Both take --data-root. Browsing itself happens through the browser tools, not the CLI.
• arc license or arc license show prints the license state offline, without a daemon. arc license verify asks the license server about the key; the answer is informational and never changes whether Arc works. arc license activate KEY and arc license deactivate go through the daemon's confirmation; --yes accepts it. A valid license keeps working offline.

Related

• CLI reference: usage and argument defaults for every command
• Connections and harness setup
• Follow state changes and wake on useful work
• HTTP, transport, and trust
• Errors and recovery