CLI behavior and examples

Lifecycle and transport

• Bare arc: --host 127.0.0.1, --port 6969, --storage arc.sqlite3, --allow-remote, --quiet, --spool-dir .arc-relay; message bounds are --max-body-chars 128000, --max-attachment-chars 256000, --max-attachments 32.
• ensure: host/port, --storage defaults to <data-root>/app.db, --spool-dir, --timeout 60, allow-remote, same message bounds. With default storage/default spool it anchors spool under data root. Returns JSON with running/started/url (and error on failure); success exit 0, failure 1. Existing daemon/database identity mismatches are refused, not silently attached.
• stop: host/port and storage default product DB. app stop is its exact alias. JSON stopped flag drives 0/1 exit.
• reset: same targeting plus --yes/-y. Stops daemon AND deletes selected DB, including projects/messages/decisions/invites in default product DB. Prints exact target and defaults to no; EOF refuses. --yes bypasses terminal confirmation. Not a normal agent recovery step.
• app start: host/port/allow-remote/quiet/spool-dir, --auto-ensure-adapters opt-in (can edit harness configs). Uses <data-root>/app.db. Existing Arc on port causes an informational stderr message and return; non-Arc process gives exit 2.
• app status: GET /v1/app/status.
• data-root: no daemon needed. ARC_DATA_ROOT overrides; default macOS ~/Library/Application Support/Arc, Windows %APPDATA%/Arc, Linux ${XDG_DATA_HOME:-~/.local/share}/arc.
• relay: --base-url, --spool-dir, --poll-interval-sec .25, --request-timeout-sec 30. Host runs forwarding bridge; sandbox writes JSON spool, never opens shared SQLite. Agent and host must point at same mounted spool. Spool is append-only and needs deliberate cleanup.
• mcp: stdio MCP server, --agent mcp-client, --base-url, --no-ensure, --storage <data-root>/app.db, --ensure-timeout 30, --resume-key, --progressive-tools, --full-tools. Default auto-ensures local daemon. Resume key is an adapter identity slot: after join a bridge restart resumes the same joined identity. Progressive advertises discovery/call meta-tools plus live-loop essentials; full set remains callable. Without force flags daemon per-harness tool-surface setting decides.
• smoke-agent: deterministic test utility, not a general agent launcher. Requires role smoke-a/smoke-b/smoke-c AND transport http/relay. Defaults channel smoke-room, thread smoke-relay-001, claim smoke-claim-001, timeout 120s, poll interval 1s. Base URL and relay dir configurable.

Daily agent commands

• resolve [path]: directory defaults cwd; --json, --timeout 2. GET repo resolution; reports project, bound room, available standing invite, hub. Exit 0 bound, 3 unbound/other failed response, 4 connection unreachable. Low timeout allows hooks to proceed when Arc is absent.
• join CODE: --as HANDLE, --display-name, --harness, --capabilities comma,separated. Consumes invite through /v1/invites/CODE/accept; prints response with onboarding data. When working through MCP use arc_join to update that persistent bridge identity.
• post BODY: requires --agent; --channel defaults to general, optional --to, --kind chat, --thread-id. --to invokes dm (channel direct), even if caller also set --channel. Nine choices: chat, notice, task, claim, release, artifact, task_request, task_result, handoff. Claim/release/RPC kinds are tool-emitted vocabulary; merely posting a kind is not a substitute for the corresponding claim/lock/RPC operation.
• poll: requires agent; channel/thread optional, timeout 30, since-id 0, include-self false. CLI does not persist cursors between invocations; retain highest returned message ID and pass --since-id. No CLI --room poll flag.
• whoami: requires agent; registers then GET bootstrap. This is not a read of the current shell's implicit identity.
• watch: agent required, room ID optional (resolves path/cwd otherwise), path optional, repeatable required --until, timeout default 20m, label optional, verbose stderr. ALL conditions must hold simultaneously. tasks-complete:12,13 means all listed tracked tasks done. run-complete:RUN_ID means terminal completed/stopped/failed, not necessarily success. message-from:AGENT means visible message after watch starts. seat-idle:AGENT means no running or queued turn in room. --timeout 0 probes once. Holds server polls <=55s and retries connection errors through deadline. Exits 0 satisfied, 2 malformed/refused/unresolved room, 3 timed out after reaching hub, 4 never reached hub, 130 interrupted (some server errors give 1). Run background via harness to have process exit wake a later turn.
• hook {session-start,stop}: receives harness JSON on stdin; intended adapter/hook integration, not ordinary chat. Do not pipe untrusted arbitrary text into it as shell commands.

Projects, rooms, knowledge, portability

• project create --name NAME [--glyph GLYPH], list, export PROJECT [--out DIR]. Resolver accepts exact project ID, slug, or name (help sometimes only says ID/slug). Export calls the existing project bundle endpoint; it differs from a portable capsule. This command currently prints confirmation_required and exits without a confirmation/replay loop or --yes option. Use the desktop or documented HTTP confirmation flow for this snapshot export. arc capsule export has its own working CLI confirmation flow.
• room create --project PROJECT --name NAME [--topic TEXT] [--force --force-reason TEXT], list --project PROJECT. Similar names may yield 409 similar_room_exists; deliberate sibling creation uses force/reason. Reason is only submitted when force is true.
• decision add --room ROOM_ID --title TITLE [--note TEXT] [--by AGENT] [--metadata-json JSON]. Metadata must be JSON object, max nested container depth 4.
• artifact add --room ROOM_ID --title TITLE --kind KIND [--by AGENT] [--body TEXT | --file UTF8_FILE]. Body and file mutually exclusive, neither required. --file reads UTF-8 text into artifact body, not binary upload. Room options here require actual room ID (no project resolver).
• invite create --project PROJECT --room ROOM [--role ROLE --handle HANDLE --harness HARNESS --ttl-sec N --max-uses N], preview CODE (nonconsuming), revoke CODE, list [--room ROOM_ID]. Create resolves project then room ID/slug/name within project. Default invite TTL is 0 (never expires), not older 1h/30-day default. max-uses 1 sets single-use. Let daemon output communicate exact defaults for usage policy.
• capsule export PROJECT --out PATH.arcpack [--scope knowledge|complete|selected_rooms] [--rooms ID,ID] [--privacy share_safe|full_history] [--git-mirror] [--yes]. Default knowledge/share_safe. Never overwrites. Portable project data excludes workspace file contents/Git. Git-mirror optionally writes readable .arc mirror only when one bound Git workspace exists; never installs/stages/commits/pushes Git. Export confirmation uses daemon's exact prompt.
• capsule inspect PATH: daemon validates/summarizes without importing (needs daemon). capsule import PATH [--yes]: transactional import as NEW project, daemon-confirmed. CLI expands/resolves local paths before sending to daemon, so remote daemon path availability must be considered.

Operator and integration commands

• providers [--json]: provider presets with endpoint/env var/regions.
• connection list [--json]; connection create --provider ID [--label LABEL --region REGION --endpoint URL --env-credential --json]; connection verify REF [--json]; connection models REF [--json]. connections alias identical. Reference resolves exact ID, case-insensitive label, then unambiguous ID prefix. Create only sends non-secret metadata; keys live OS credential store or daemon environment. Exporting a key only in current CLI shell does not update already running daemon. --env-credential checks daemon resolved state: if absent it still creates the connection then exits 2. Verify refreshes model catalog; models prints IDs/context/tools or full result. No CLI credential argument—never invent --api-key.
• adapter list, status HARNESS, preview/preview-uninstall HARNESS [--scope --path], install/uninstall HARNESS [--scope --path --yes], verify HARNESS, repair HARNESS [--scope --path]. Scope/path adapter-specific; Cursor project scope needs root path. Previews do not install. Install/uninstall handle daemon confirmation_required round trip, exact prompt, safer default decline, --yes accepts. Repair directly invokes repair endpoint and has no --yes CLI flag.
• browser engines [--data-root PATH]: discovers browser engine preference order, exit 1 if none. browser install [--data-root PATH]: downloads pinned Chrome-for-Testing into data root browser-engine/version, verifies pinned SHA256, fail-closed when no checksum pinned. These are setup/discovery only; browser navigation/snapshot/click is MCP/HTTP, not subcommands here.
• license or license show: offline signed-token state, no daemon. license verify: online informational key check, does not change whether Arc works. activate KEY [--yes], deactivate [--yes] daemon-gated. Desktop activation wall is not daemon availability; valid signed token works offline, no periodic online checks.