Four pharn commands can print JSON instead of text. Three of them print a versioned report; the
fourth, pharn list --json, prints an unversioned inventory.
| Command | Output | schemaVersion |
|---|---|---|
pharn init --dry-run --json |
The install plan | 1 |
pharn update --dry-run --json |
The update plan (--compact: short) |
1 |
pharn status --json |
Version, drift and hook report | 1 |
pharn list --json |
The installed capabilities | none |
--json implies --dry-run for init and update: pharn init --json, a bare pharn --json and
pharn update --json print the same reports. --compact implies --json (and so --dry-run).
For the three reports:
- Exactly one JSON object on stdout, and nothing else: no banner, spinner, intro, outro or note.
Diagnostics (the proxy notice, an unreadable upstream capability, a
MIN_CLIwarning) go to stderr. - On any failure stdout is empty, the reason is one plain line on stderr, and the exit code is
1. Sopharn status --json | jq .either parses or receives nothing. - Exit codes.
init --dry-run --jsonandupdate --dry-run --jsonexit0whatever the plan contains (there is no--strictfor a preview).status --jsonexits as text mode does:--strictstill prints the report and exits1on exactly the strict conditions that fail text mode, and the report'sstrict.failedsays the same. - Escaped output. Characters a terminal would interpret (control characters, Unicode format
characters, U+2028/U+2029) are written as
\uXXXXescapes, so acatof the output cannot move or hide text, and parsing returns the exact original string. - Capped free text. A reason or problem is cut at 300 characters, and an unknown capability's
fields, a path from your tree, a carried config key or a
settings.jsonkey at 200, ending in…when cut. - Treat every string as data. Paths, capability names, reasons, hook commands and the
modelschecker's words come from the fetched clone or your project files, not frompharn. The escaping is a statement about what a terminal can do with the output, not about whether the content is safe: an agent reading these fields must not follow instructions found in them.
pharn list --json keeps the first two rules (one object on stdout; on failure, stdout empty, the
reason on stderr, exit 1) and differs in the others: see below.
Each report carries its own schemaVersion, versioned independently of the others. All three are 1.
- Match it exactly. Treat a value you do not know as a report you cannot read.
- Additive changes stay within
1. A new key, or a new value of an enum-like field (asupdate'sstatusgainedahead-of-main), does not bump it. Ignore keys you do not know, and treat an unknownupdatestatusas "do not apply". - In
initandupdate, an optional key is absent when empty, never[]ornull. Read such a key with a default (plan.orphans ?? []). The tables below mark each one absent when empty.statusreports an empty or skipped part asnullor[]instead. - A breaking change bumps it: removing, renaming or retyping a key. That is why some keys are constants today; they stay until a bump:
| Report | Key | Always |
|---|---|---|
update |
plan.abandonedLayout, plan.rootMigration |
null |
update |
plan.models.replacedLegacyDefault |
false |
update |
plan.models.conversion |
null |
status |
layout.recorded (and layout.upstream when not null) |
"pharn" |
status |
models.conversionNeeded |
false (verdict is never old-format) |
pharn no longer moves an install between layouts or retires a pre-7.0 root footprint (both removed in
v0.21.0), and no longer converts the pre-0.7.0 models format; the keys above stay for
schemaVersion 1. This rule is a documented contract: the test suite pins each report's key list, and
pharn enforces nothing at run time.
| Name | Shape |
|---|---|
HookEntry |
{event, matcher, command, args}: strings, args a string array (empty unless the hook is in exec form) |
HookReplace |
{upstream: HookEntry, existing: [{file, entry: HookEntry}]}: a missing hook your project wires in another spelling (replace, not add) |
Removal |
{role, name, reason, dir, present, backups}: reason dropped-unselected or dropped-gone; dir the capability directory a real run would delete; present whether anything is there; backups the files in it copied to pharn/.backup/<timestamp>/ first |
IgnoreEdit |
{action, entries} with action create or append and entries the lines added, or {action: "refused", reason, entries} with reason symlink, not-a-file or unreadable and the lines to add yourself |
Absent |
{surface, path}: a declared surface the fetched clone ships no file for; surface is commands, hooks, trusted-doc, license, features-readme, contracts, core or floor |
Unknown |
{role, name, subtree, reason}: an upstream capability this pharn cannot read, skipped |
Orphan |
{path, state} with state unchanged, edited or unreadable (then also reason): a recorded file upstream no longer ships, still on disk |
Hooks |
{status, missing: HookEntry[], localOnly: HookEntry[], file, reason} plus replace: HookReplace[] (absent when empty). status is match, local-only, missing, no-upstream, project-absent or unreadable; file/reason name an unreadable settings file, else null |
The plan pharn init would carry out, from the same planner as the text preview; it writes nothing.
See pharn init for what the plan means.
| Key | Type | Notes |
|---|---|---|
schemaVersion |
1 |
|
command, dryRun, status |
"init", true, "planned" |
Constants. |
channel |
"latest" or "main" |
main under --ref main. |
source |
{kind, tag} |
kind release (with its tag) or main (tag null). |
commit |
string or null |
The commit the plan was made from. |
skillsVersion |
string | The version upstream ships. |
layout |
"pharn" |
|
archetypes |
string array | The archetypes the install uses (ssr, backend, spa, lib). |
archetypeSource |
"detected" or "flag" |
flag under --archetype. |
detectedArchetypes |
string array or null |
With flag: what detection found and did not use. null otherwise. |
archetypeEvidence |
{archetype, source, value}[] |
Detection's trigger per archetype it found: source dependency or devDependency (value the package name), path (the first triggering path, a directory ending in /) or none (lib, value null). Always detection's, also under flag. |
detectionTruncated |
true |
Absent when empty. Present only when detection's scan stopped at a bound (50,000 entries, 24 directories deep) before its result was settled. |
capabilities.selected |
{role, name, matched}[] |
matched is "universal", "manual" or the archetypes that selected it. |
capabilities.skipped |
{role, name, reason}[] |
Capabilities upstream ships that this install leaves out. |
capabilities.carried |
{manual, kept, dropped} |
role:name keys from the config a re-install replaces: manual entries (pharn add) it keeps, kept entries this pharn cannot read (kept verbatim), dropped manual entries upstream no longer ships. Empty on a first install. |
capabilities.removals |
Removal[] |
Absent when empty. The capability directories a re-install would delete. |
unknownCapabilities |
Unknown[] |
|
targets |
{rel, action, label}[] |
Every file the install writes, plus pharn.config.json, sorted. action create or overwrite. label modified, unrecorded or unverifiable (backed up first), rewritten (an existing pharn.config.json, always backed up), else null. |
backups |
string array | The files copied to pharn/.backup/<timestamp>/ first. |
counts |
{create, overwrite, backup} |
Numbers. |
yesWouldProceed |
boolean | Whether pharn init --yes would install now: true only when nothing would be overwritten. |
settings.preserved |
boolean | Whether .claude/settings.json exists and is kept. |
hooks |
Hooks or null |
The hook comparison against a preserved settings.json. null when there is none to preserve. |
settingsHooks |
{status: "ok", hooks: HookEntry[], otherKeys, skipped} or {status: "unreadable", reason} |
Absent when empty. Present only when the install would write .claude/settings.json from upstream: what that file wires, its other top-level keys (sorted) and the number of hook entries pharn could not read. |
absentUpstream |
Absent[] |
Absent when empty. |
models |
{outcome, reasons} |
outcome copy, none (upstream ships no block) or rejected (with reasons). The block itself is not included. |
config.carriedKeys |
string array | Your own config keys the install keeps, by name only. |
gitignore |
IgnoreEdit |
Absent when empty. Present only when the install would change .gitignore, or would have to leave it alone. |
prettierignore |
IgnoreEdit |
Absent when empty. The same for .prettierignore, in a project that uses Prettier. |
A non-null label in targets means the file is in backups; the overwrite prompt shows modified,
unrecorded and unverifiable as (edited), (no pharn record) and (differs from upstream).
A fresh project with next in its dependencies:
pharn init --dry-run --json{
"schemaVersion": 1,
"command": "init",
"dryRun": true,
"status": "planned",
"channel": "latest",
"source": { "kind": "release", "tag": "v7.22.0" },
"commit": "9422b97f9bcef022d240822024e75a1a49c6e278",
"skillsVersion": "7.22.0",
"layout": "pharn",
"archetypes": ["ssr"],
"archetypeSource": "detected",
"detectedArchetypes": null,
"archetypeEvidence": [
{ "archetype": "ssr", "source": "dependency", "value": "next" }
],
"capabilities": {
"selected": [
{ "role": "griller", "name": "a11y", "matched": ["ssr"] },
{ "role": "griller", "name": "architecture", "matched": "universal" }
],
"skipped": [],
"carried": { "manual": [], "kept": [], "dropped": [] }
},
"unknownCapabilities": [],
"targets": [
{
"rel": ".claude/agents/pharn-review-lens.md",
"action": "create",
"label": null
},
{
"rel": ".claude/commands/pharn-plan.md",
"action": "create",
"label": null
},
{ "rel": "pharn.config.json", "action": "create", "label": null },
{ "rel": "pharn/CONSTITUTION.md", "action": "create", "label": null }
],
"backups": [],
"counts": { "create": 614, "overwrite": 0, "backup": 0 },
"yesWouldProceed": true,
"settings": { "preserved": false },
"hooks": null,
"settingsHooks": {
"status": "ok",
"hooks": [
{
"event": "PreToolUse",
"matcher": "Write|Edit|MultiEdit|NotebookEdit",
"command": "node \"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/protect-trusted-paths.cjs",
"args": []
}
],
"otherKeys": [],
"skipped": 0
},
"models": { "outcome": "copy", "reasons": [] },
"config": { "carriedKeys": [] },
"gitignore": {
"action": "create",
"entries": ["pharn/.run/", "pharn/.backup/"]
}
}Trimmed: capabilities.selected shows 2 of 35 entries, targets 4 of 614 and settingsHooks.hooks 1
of 3.
The plan pharn update would carry out; it writes nothing. It composes with --force and --ref;
--yes is accepted and does nothing. See pharn update
for what the plan means.
The outcome is status:
status |
Meaning | plan |
|---|---|---|
planned |
A real run would proceed. | object |
up-to-date |
The plan changes nothing: a real run would ask nothing and write nothing (it may still keep an edit of yours). | null |
ahead-of-release |
The install is newer than the newest verified release (--ref latest); nothing changes without --force. |
null |
ahead-of-main |
The install is newer than pharn-oss main; nothing changes without --force. |
null |
| Key | Type | Notes |
|---|---|---|
schemaVersion |
1 |
|
command, dryRun |
"update", true |
Constants. |
compact |
true |
Present only under --compact, on every status. |
status |
string | The table above. |
force |
boolean | Whether --force was passed. |
channel |
"latest" or "main" |
The channel this run used. |
channelChange |
{from, to} or null |
Set when --ref would switch the recorded channel. |
source |
{kind, tag} |
kind release (with its tag) or main (tag null). |
version |
{installed, latest, recorded, withheld, pending} |
installed: recorded now; latest: what upstream ships. With a plan: recorded is the version a real run would record, withheld says skipped files would hold it back, pending the pendingSkillsVersion a real run would record (else null). The last three are null without a plan. |
archetypes |
string array | The recorded archetypes. |
plan |
object or null |
Set only when status is planned. Its keys follow. |
plan.layout |
"pharn" |
abandonedLayout and rootMigration beside it are always null. |
plan.featuresReadmeRelocation |
boolean | Whether a copy of the boundary contract would be left at the project root. |
plan.capabilities |
{count, changes} |
The count after the update and every membership change as {role, name, source, reason}: source auto, manual or null; reason added, dropped-unselected, dropped-gone, kept-manual or kept-frozen. |
plan.capabilities.removals |
Removal[] |
Absent when empty. The directories a real run would delete. |
plan.files |
{rel, action, label, backup, forced}[] |
Every installed file. action write, noop or skip; label restored, updated, ok, or a skip reason (modified, unrecorded, unverifiable, unreadable, held); forced: --force made it a write; backup: copied first. |
plan.filesOmitted |
{action: "noop", count} |
Present only under --compact: what files leaves out. count equals counts.ok. |
plan.writes |
string array | The files a real run would write, in install order. |
plan.backups |
string array | The files copied to pharn/.backup/<timestamp>/ first (pharn.config.json too when --force replaces your models block). |
plan.skipped |
{label, rels}[] |
Skipped files grouped by reason, most actionable first. |
plan.counts |
{updated, restored, ok, forced, skipped} |
Totals; never filtered by --compact. |
plan.executableUnit |
{blocking, held, missing} |
Absent when empty. The executable-unit hold: blocking the skipped unit files as {rel, label}, held the unit files not written because of them, missing (absent when empty) the held files not on disk. |
plan.models |
{outcome, label, replacedLegacyDefault, backup, conversion, problems, upstreamReasons} |
outcome restored, updated, ok, kept, forced, upstream-absent or upstream-invalid; label the skip label when the block is yours, else null; backup: pharn.config.json copied first. The block itself is not included. |
plan.hooks |
Hooks |
The same comparison as status --json. update never writes your settings files. |
plan.absentUpstream |
Absent[] |
Absent when empty. |
plan.frozenCapabilities |
string array | role:name of capabilities upstream ships that this pharn cannot read, kept as they are. |
plan.unknownCapabilities |
Unknown[] |
|
plan.recordsNote |
string or null |
Why pharn.records.json could not be used (every difference is then unverifiable). |
plan.orphans |
Orphan[] |
Absent when empty. Never filtered by --compact. |
plan.gitignore, plan.prettierignore |
IgnoreEdit |
Absent when empty. Present only when a real run would change the file, or would have to leave it alone. |
plan.files lists every installed file, most of them noop on a large install.
pharn update --dry-run --json --compact leaves out exactly the noop entries, adds compact: true
and plan.filesOmitted, and changes nothing else: files.length + filesOmitted.count is the
installed-file total. The default report has neither key and always holds the full list.
The project from the init example after pharn init --yes, with one installed file edited
(.claude/commands/pharn-plan.md) and one deleted (pharn/CONSTITUTION.md):
pharn update --dry-run --json{
"schemaVersion": 1,
"command": "update",
"dryRun": true,
"status": "planned",
"force": false,
"channel": "latest",
"channelChange": null,
"source": { "kind": "release", "tag": "v7.22.0" },
"version": {
"installed": "7.22.0",
"latest": "7.22.0",
"recorded": "7.22.0",
"withheld": true,
"pending": null
},
"archetypes": ["ssr"],
"plan": {
"layout": "pharn",
"abandonedLayout": null,
"featuresReadmeRelocation": false,
"rootMigration": null,
"capabilities": { "count": 35, "changes": [] },
"files": [
{
"rel": ".claude/agents/pharn-review-lens.md",
"action": "noop",
"label": "ok",
"backup": false,
"forced": false
},
{
"rel": ".claude/commands/pharn-plan.md",
"action": "skip",
"label": "modified",
"backup": false,
"forced": false
},
{
"rel": "pharn/CONSTITUTION.md",
"action": "write",
"label": "restored",
"backup": false,
"forced": false
}
],
"writes": ["pharn/CONSTITUTION.md"],
"backups": [],
"skipped": [
{ "label": "modified", "rels": [".claude/commands/pharn-plan.md"] }
],
"counts": {
"updated": 0,
"restored": 1,
"ok": 611,
"forced": 0,
"skipped": 1
},
"models": {
"outcome": "ok",
"label": null,
"replacedLegacyDefault": false,
"backup": false,
"conversion": null,
"problems": [],
"upstreamReasons": []
},
"hooks": {
"status": "match",
"missing": [],
"localOnly": [],
"file": null,
"reason": null
},
"frozenCapabilities": [],
"unknownCapabilities": [],
"recordsNote": null
}
}Trimmed: plan.files shows the first entry and the two that are not noop, of 613. withheld is
true because the skipped edit holds the version back.
The version, drift and hook report, on the default path and under --no-drift. See
pharn status for what each part means.
| Key | Type | Notes |
|---|---|---|
schemaVersion |
1 |
|
node |
{floor, running, status} |
The floor (24.2.0), the running Node (null when it reports none) and status ok, below or unparseable. Never a --strict input. |
version |
{installed, latest, channel, source, ahead, outdated} |
The installed and latest skills versions, channel latest or main, source {kind, tag} as in the other reports, ahead (newer than the source it follows) and outdated. |
archetypes |
string array | The recorded archetypes. |
capabilities.count |
number | The list itself is pharn list --json. |
layout |
{recorded, upstream} |
Both "pharn"; upstream is null under --no-drift. |
drift |
object or null |
{modified, missing, unreadable, okCount, absentUpstream}: modified and missing path arrays, unreadable as {rel, reason}[], okCount a number, absentUpstream an Absent[] (always present here). null under --no-drift. |
hooks |
Hooks or null |
null under --no-drift. |
models |
object or null |
null without a models block; else {conversionNeeded, verdict, stages, reds}: verdict valid, no-stages or invalid; stages {stage, model, effort, viaDefault}[] when valid, else null; reds {kind, detail}[] when invalid, else null. |
unknownCapabilities |
Unknown[] or null |
null under --no-drift. |
orphans |
Orphan[] or null |
null under --no-drift or without a usable pharn.records.json. Never a --strict input. |
prettierignore |
IgnoreEdit or null |
What pharn update would do to .prettierignore; null when there is nothing to say or no usable pharn.records.json. Answered under --no-drift too. Never a --strict input. |
strict |
{enabled, failed} |
--strict passed, and whether it exits 1 (the strict conditions). |
Unlike the other two reports, status --json reports an empty or skipped part as null or []
rather than leaving the key out; only hooks.replace is absent when empty.
The same project as the update example:
pharn status --json{
"schemaVersion": 1,
"node": { "floor": "24.2.0", "running": "24.13.1", "status": "ok" },
"version": {
"installed": "7.22.0",
"latest": "7.22.0",
"channel": "latest",
"source": { "kind": "release", "tag": "v7.22.0" },
"ahead": false,
"outdated": false
},
"archetypes": ["ssr"],
"capabilities": { "count": 35 },
"layout": { "recorded": "pharn", "upstream": "pharn" },
"drift": {
"modified": [".claude/commands/pharn-plan.md"],
"missing": ["pharn/CONSTITUTION.md"],
"unreadable": [],
"okCount": 611,
"absentUpstream": []
},
"hooks": {
"status": "match",
"missing": [],
"localOnly": [],
"file": null,
"reason": null
},
"models": {
"conversionNeeded": false,
"verdict": "valid",
"stages": [
{
"stage": "default",
"model": "sonnet",
"effort": "high",
"viaDefault": false
},
{
"stage": "spec",
"model": "opus",
"effort": "high",
"viaDefault": false
},
{
"stage": "triage",
"model": "sonnet",
"effort": "high",
"viaDefault": true
}
],
"reds": null
},
"unknownCapabilities": [],
"orphans": [],
"prettierignore": null,
"strict": { "enabled": false, "failed": false }
}Trimmed: models.stages shows 3 of 14 rows.
The installed archetypes and capabilities, read from pharn.config.json alone: no download, no lock.
See pharn list.
It is unversioned. It has no schemaVersion and is not covered by the stability rule above. It is
printed with plain JSON.stringify, without the \uXXXX escaping of the reports: every value it
prints passed an allowlist when the config was loaded (skillsVersion a version, the archetypes and
roles from fixed sets, a capability name one lowercase, hyphen-separated segment, source auto or
manual), so none can hold a character a terminal would interpret.
| Key | Type | Notes |
|---|---|---|
mode |
"archetype" |
The only mode. |
skillsVersion |
string | The installed content version. |
archetypes |
string array | The recorded archetypes. |
capabilities |
{name, role, source}[] |
In config order. role griller or lens. source is absent when the config does not record it (provenance not yet known), never defaulted. |
The same project:
pharn list --json{
"mode": "archetype",
"skillsVersion": "7.22.0",
"archetypes": ["ssr"],
"capabilities": [
{ "name": "a11y", "role": "griller", "source": "auto" },
{ "name": "architecture", "role": "griller", "source": "auto" },
{ "name": "copy-paste-drift", "role": "lens", "source": "auto" }
]
}Trimmed: capabilities shows 3 of 35 entries.
Each example is real output of the CLI built from this repository (npm run build; pharn below is
node <checkout>/dist/index.js), run on 2026-11-17 against the pharn-oss v7.22.0 release, in a new
project whose package.json lists next in its dependencies, after git init:
pharn init --dry-run --json # the init example, before installing
pharn init --yes
# then: append a line to .claude/commands/pharn-plan.md and delete pharn/CONSTITUTION.md
pharn update --dry-run --json # the update example
pharn status --json # the status example
pharn list --json # the list exampleThe output was re-indented to fit this page; the trims are named under each example, and every key and value shown is as printed. A newer pharn-oss changes the versions, the commit and the counts.