CLI reference

patcharc has no persistent flags beyond --help / -h and --version / -v. Every command resolves the repository by walking up from the current directory until it finds .git or .patcharc. Errors print patcharc: <message> to stderr and exit 1.

Local loop

patcharc init [--force]

Initialize .patcharc/ in the current repository: config.yaml, keys/arc-signing.ed25519 (0600), session.db, repo_id, worktree_id, and .gitignore entries. Fails if .patcharc/ exists unless --force, which rotates the signing key.

patcharc start [goal] [--detach]

Start an Arc. goal defaults to Untitled Arc. --detach spawns the background observer (PID in .patcharc/observer.pid, log in .patcharc/observer.log). Without it the observer runs for 1.5 seconds and exits. Requires init; fails if an Arc is already active.

patcharc status

Print the active Arc: id, status, goal, branch, head before, commit and file counts. With no active Arc prints No active Arc. Run patcharc start [goal]. and exits 0.

patcharc note <text> · patcharc decision <text> · patcharc risk <text>

Attach a timestamped entry to the active Arc. Text is required (quote it). Prints ✓ <kind> recorded.

patcharc checkpoint [note]

Record the current HEAD as a checkpoint with an optional label. Prints ✓ Checkpoint #N recorded.

patcharc stop [--share]

Stop the observer, compute the review, seal the capsule to .patcharc/capsules/<arc_id>.parc, and print the inspect and verify commands. --share prints a reminder to run patcharc share; it does not upload.

patcharc verify <capsule>

Verify a .parc offline: path safety, compression ratio, manifest, signature, every file hash and size. Prints ✓ <arc> is valid (…) and exits 0, or ✗ <arc> is INVALID with one line per issue and exits 1.

patcharc inspect <capsule>

Run the same verification and print a table: capsule id, format, file count and bytes, and the result of each check.

patcharc serve [capsule] [--port 7777]

Serve on 127.0.0.1:<port> until Ctrl-C. GET /api/capsule?file=<absolute path under .patcharc/capsules> returns the verified review JSON; other paths are refused. The placeholder page at / has no viewer yet.

patcharc scopes · patcharc scopes:graph

List detected or configured scopes; print the depends_on graph as Graphviz DOT. See Monorepo scopes.

patcharc doctor

Check that git resolves, .git exists, config.yaml exists, and the signing key exists. Always exits 0.

Cloud

patcharc login

Device-flow sign-in (GitHub or Google). Writes ~/.patcharc/credentials.json (0600). See Accounts and sessions.

patcharc logout

Delete the credentials file.

patcharc share [--file <path>] [--visibility public|private|team|capability] [--open] [--no-ai]

Upload the newest capsule (or --file), wait for server-side verification (2-second polls, 2-minute limit), create the share, print the ArcLink. --visibility defaults to public. --no-ai defaults to on and has no effect in 0.2.0. Requires login.

Print-only in 0.2.0

These commands exist so scripts and documentation can reference a stable name, but they print a message and exit 0 without acting:

patcharc __observer is the hidden internal command that start --detach launches; do not run it yourself.

Environment variables

No other environment variables are read. See Configuration for config.yaml and Exit codes and output.