# CLI behavior and examples

Arc agent documentation

Lifecycle defaults, identity changes, watch conditions, provider setup, and operator commands.

## 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.