Exit codes and output
How patcharc signals success and failure, the shape of its output, and how to consume results from scripts.
validated against patcharc 0.2.0 · 2026-08-22
Exit codes
| Code | Meaning |
|---|---|
0 | Success. Also returned by status with no active Arc and by every print-only command |
1 | Any error: not in a repository, no active Arc, verify found issues, network failure, login required, unknown flag or wrong argument count |
Only verify turns the content of a file into a non-zero exit; use it as a gate in scripts and CI.
Output conventions
- Success lines start with
✓; failures with✗. - Detail lines are indented two spaces with aligned labels (
goal:,key:,ArcLink:). - Errors go to stderr as
patcharc: <message>. - There is no
--jsonflag and no--quietflag in 0.2.0.
Machine-readable data
Read the capsule directly instead of parsing console output:
$ unzip -p capsule.parc manifest.json | jq '.totals'
$ unzip -p capsule.parc evidence/summary/review.json | jq '.risks[].text'
$ unzip -p capsule.parc evidence/file_changes.json | jq 'length'patcharc serve also returns the review as JSON at /api/capsule?file=<absolute path> after verifying the capsule.
Common error messages
| Message | Cause |
|---|---|
not inside a Git repository or PatchArc session (cwd=…) | No .git or .patcharc found walking up from the current directory |
.patcharc/ already exists; use --force to reinitialise (this will rotate the signing key) | init on an initialized repo |
no active session | note, decision, risk, checkpoint, or stop without a running Arc |
share: not logged in — run patcharc login first | No credentials file |
share: no sealed capsules in … — run patcharc stop first | Nothing in .patcharc/capsules/ |
share: invalid --visibility "x" (want public|private|team|capability) | Unknown visibility |
share: capsule processing failed (step "verify_manifest_and_archive": …) | The server could not verify the capsule |
share: timed out waiting for capsule processing | More than 2 minutes in verifying; check /v1/capsules/:id/status |
login: device code expired; run patcharc login again | Approval took longer than 10 minutes |