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 two .gitignore lines that ignore everything under .patcharc/ except config.yaml. 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 share.default from .patcharc/config.yaml (private unless you change it). --no-ai defaults to on and has no effect in 0.2.0. Requires login.

patcharc run [--framework <name>] [--junit <glob>] -- <command> [args...]

Run any command inside the active Arc and record what happened. Output from go test, pytest, vitest, jest, playwright, and cargo test is parsed into pass/fail/skip counts that fill the review's Verification section; --junit imports JUnit XML reports instead. The child's exit code passes through, so wrapping commands in CI is safe. Commands with no recognisable test output are still recorded as command events.

patcharc open [capsule]

Open a sealed capsule in the embedded viewer: a loopback-only port, your browser, nothing uploaded. Defaults to the newest capsule; --no-browser prints the URL instead.

patcharc preview

Show what the active Arc has captured so far — commits, line counts, test runs, decisions, risks — without sealing or touching the network.

patcharc redact [file...]

Dry-run the configured redaction rules and report what would be removed at seal time. With no arguments it scans the active Arc's commit diffs; files are never modified.

patcharc hooks install|uninstall|status

Manage the git hooks behind ambient capture: post-commit reconciles new commits immediately, post-rewrite records rebase and amend mappings as rewrite evidence, post-merge/post-checkout keep the Arc current. Blocks are appended between markers, existing hooks are preserved, and every line ends in || true so a commit can never fail because of PatchArc. --auto-start also enables capture.auto_start, which opens an Arc automatically when a commit lands with none active (patcharc init --auto does both at once).

patcharc mcp

Serve PatchArc over the Model Context Protocol on stdio. Any MCP-capable agent can then start and stop Arcs, record decisions, risks, notes, and test results, and verify capsules: claude mcp add patcharc -- patcharc mcp.

patcharc attest <capsule> [--out <path>] [--print]

Verify a capsule and emit a signed in-toto Statement (DSSE envelope) binding the resulting commit and the capsule digest to the recorded process evidence, for consumption by standard provenance tooling.

Print-only in 0.2.x

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.