Pinman CLI Reference

Pinman 2.0.261115-c90f0b8 Beta — generated 2026-11-15

pinman auth

 Usage: pinman auth [OPTIONS] COMMAND [ARGS]...

 Manage UI login PINs (roles.json in the project home).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ list    List the login roles (PINs are never shown).                        │
│ reset   Reset ROLE's PIN back to its factory default.                       │
│ set     Set ROLE's PIN (operator or technician). PIN must be 4-8 digits.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman auth list

 Usage: pinman auth list [OPTIONS]

 List the login roles (PINs are never shown).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman auth reset

 Usage: pinman auth reset [OPTIONS] ROLE

 Reset ROLE's PIN back to its factory default.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ROLE  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman auth set

 Usage: pinman auth set [OPTIONS] ROLE PIN

 Set ROLE's PIN (operator or technician). PIN must be 4-8 digits.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ROLE     TEXT  [required]                                                │
│ *  NEW_PIN  PIN   [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box

 Usage: pinman box [OPTIONS] COMMAND [ARGS]...

 Manage boxes (device grouping containers).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Boxes ─────────────────────────────────────────────────────────────────────┐
│ list       List all boxes.                                                  │
│ show       Show box detail with devices, setup profile, and drift status.   │
│ create     Create a new box.                                                │
│ rename     Rename a box.                                                    │
│ delete     Delete a box (devices are unassigned, not deleted).              │
│ use        Switch to a root box (make it the active box), deactivating the  │
│            current one.                                                     │
│ set-setup  Set the setup profile for a box.                                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Computer membership ───────────────────────────────────────────────────────┐
│ assign    Add the Computer to a box: `box assign computer --box <box>`.     │
│ unassign  Remove the Computer from a box: `box unassign computer --box      │
│           <box>`.                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box assign

 Usage: pinman box assign [OPTIONS] SUBJECT

 Add the Computer to a box: `box assign computer --box <box>`.
 Device↔box membership is device-side — use `pinman device assign --box`.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  SUBJECT  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --box                     TEXT  Box name to add the Computer to.         │
│                                    [required]                               │
│    --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│    --help             -h,-?        Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box create

 Usage: pinman box create [OPTIONS] NAME

 Create a new box.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --type                    TEXT  Box type (e.g. computer, enclosure,      │
│                                    controller). [required]                  │
│    --parent                  TEXT  Parent box name (for nesting).           │
│    --active                        Mark as active system root.              │
│    --description             TEXT  Box description.                         │
│    --setup-profile           TEXT  Setup profile path (relative to profiles │
│                                    dir).                                    │
│    --setup-inputs            TEXT  Setup profile inputs as JSON, e.g.       │
│                                    '{"volume":75}'.                         │
│    --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│    --help             -h,-?        Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box delete

 Usage: pinman box delete [OPTIONS] NAME

 Delete a box (devices are unassigned, not deleted).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box list

 Usage: pinman box list [OPTIONS]

 List all boxes.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box rename

 Usage: pinman box rename [OPTIONS] NAME NEW_NAME

 Rename a box.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME      TEXT  [required]                                               │
│ *  NEW_NAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box set-setup

 Usage: pinman box set-setup [OPTIONS] NAME

 Set the setup profile for a box.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --setup-profile           TEXT  Profile path relative to profiles dir.   │
│                                    [required]                               │
│    --setup-inputs            TEXT  Profile inputs as JSON, e.g.             │
│                                    '{"volume":75}'.                         │
│    --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│    --help             -h,-?        Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box show

 Usage: pinman box show [OPTIONS] [NAME]

 Show box detail with devices, setup profile, and drift status.
 If NAME is given, show that box only. Otherwise show all boxes.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box unassign

 Usage: pinman box unassign [OPTIONS] SUBJECT

 Remove the Computer from a box: `box unassign computer --box <box>`.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  SUBJECT  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --box                     TEXT  Box name to remove the Computer from.    │
│                                    [required]                               │
│    --force            -f           Skip the confirmation prompt (and        │
│                                    authorize the op when non-interactive).  │
│    --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│    --help             -h,-?        Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman box use

 Usage: pinman box use [OPTIONS] NAME

 Switch to a root box (make it the active box), deactivating the current one.
 If the box has a setup profile configured, shows its drift status and offers
 to apply it, then runs `profile apply`'s display countdown and guided
 actions. `--force` applies without prompting or the countdown; `--no-apply`
 skips it.
 Under `machine_readonly` the setup-profile apply is previewed; pass
 `--allow-writes` to authorize this one invocation to write.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --no-apply                Switch only; skip the setup-profile apply prompt. │
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --allow-writes            Write to the machine even though machine_readonly │
│                           is enabled.                                       │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture

 Usage: pinman capture [OPTIONS] COMMAND [ARGS]...

 Manage system state captures (checkpoints, savepoints, and their backups).
 Maintenance verbs (repair-head, unlock, clean, workers) live under `pinman
 capture maint`.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ broaden   Broaden a capture — widen its floor and materialize to it, in     │
│           place.                                                            │
│ capacity  Report free space vs. estimated savepoint size on backups_root.   │
│ chain     Show a capture's history chain (newest -> oldest).                │
│ changes   Show a capture's changes vs its baseline (read-only; creates      │
│           nothing).                                                         │
│ check     Check a capture's record and item rows for internal               │
│           contradictions.                                                   │
│ cleanup   Bulk-delete captures matching filters (chain-safe).               │
│ coverage  Show a capture's coverage: its base floor plus every              │
│           per-container extension.                                          │
│ create    Freeze the head into a new capture (the kind is derived from the  │
│           levers).                                                          │
│ delete    Delete a capture (chain-safe).                                    │
│ dump      Dump a capture's items tree as JSON/YAML.                         │
│ list      List existing captures.                                           │
│ maint     Capture maintenance: repair the head, clear the lock, prune       │
│           incompletes, tune workers.                                        │
│ move      Move/relocate backed up captures and update database references.  │
│ refresh   Refresh the head — re-read live values for its existing coverage. │
│ restore   Restore LOCATIONS as capture CAPTURE_ID recorded them; its files  │
│           when none are named.                                              │
│ show      Show a capture with its hierarchical items tree.                  │
│ verify    Verify the stored bytes of a backed up capture.                   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture broaden

 Usage: pinman capture broaden [OPTIONS] [ID]

 Broaden a capture — widen its floor and materialize to it, in place.
 Defaults to the head; select a frozen capture by positional ID or `--latest`
 (the newest backup), which may broaden granularity from its stored bytes.
 Relax-only: each lever may stay or widen (--scope discovery widens tracked →
 discovery; --granularity settings widens file → settings); narrowing or a
 no-op is an error. The floor (`scan_props_json`) is rewritten and the kind
 label re-derives (e.g. File Checkpoint → Checkpoint). The granularity axis
 reads held data (the head's extract, or a frozen backup capture's stored
 bytes); the scope axis re-extracts the newly-in-scope breadth (head only —
 frozen captures never read live). CLI counterpart of the Explore toolbar's
 Broaden (API `POST /captures/{id}/broaden`); run synchronously here.
 With --item LOCATION, broadens ONE container instead (API `POST
 /captures/{id}/items/{iid}/broaden`): the scope axis is a surgical live read
 of that container's immediate children (winreg subtrees above the size gate
 run regardless here — the CLI is the confirmed path); on a frozen capture
 only backed up real-file rows can serve scope from stored bytes. The capture
 floor and kind label are untouched.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                 Select the newest item (mutually   │
│                                          exclusive with a positional        │
│                                          ID/NAME).                          │
│ --item                      TEXT         Broaden ONE container: the item    │
│                                          location (e.g. 'fs:/c:/MyApp/...', │
│                                          'winreg:/HKEY_CURRENT_USER/...'),  │
│                                          resolved as the capture sees it —  │
│                                          a row shared from an ancestor      │
│                                          capture is addressable. Requires   │
│                                          an axis flag. The capture          │
│                                          floor/kind are untouched           │
│                                          (container broaden is view-extent  │
│                                          coverage).                         │
│ --scope                     [discovery]  Widen scope: tracked → discovery   │
│                                          (head only)                        │
│ --granularity               [settings]   Widen granularity: file → settings │
│ --include-hidden                         With --item: also list the         │
│                                          container's untracked hidden and   │
│                                          temporary entries (head only;      │
│                                          until the next capture). Implies   │
│                                          --scope discovery where needed.    │
│ --no-winreg-extract                      Skip winreg extraction             │
│                                          (whole-capture scope axis; use     │
│                                          when already extracted)            │
│ --no-winrt-extract                       Skip winrt extraction              │
│                                          (whole-capture scope axis; use     │
│                                          when already extracted)            │
│ --verbose/--quiet    -v/-q               Echo/hide detailed output incl.    │
│                                          progress logs (applies to the      │
│                                          whole run; default quiet —         │
│                                          PINMAN_VERBOSE env var sets the    │
│                                          default).                          │
│ --help               -h,-?               Show this message and exit.        │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture capacity

 Usage: pinman capture capacity [OPTIONS]

 Report free space vs. estimated savepoint size on backups_root.
 Default: estimates a full savepoint (all tracked fs files + winreg/winrt
 extracts). With --for-next-backup, estimates only the delta vs. the last
 completed savepoint.
 Classifies as ``ok``, ``low``, or ``not_enough`` against
 ``backup_capacity_low_multiplier`` (default 3x). Exit codes for scripting: 0
 = ok, 1 = low, 2 = not_enough.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --for-next-backup                       Estimate space for the next         │
│                                         incremental savepoint (files        │
│                                         modified since the last completed   │
│                                         savepoint). Falls back to a full    │
│                                         estimate when no prior savepoint    │
│                                         exists. Used by the savepoint       │
│                                         pre-flight check.                   │
│ --force-estimate                        Use the heuristic for extract sizes │
│                                         even if real extract files exist.   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture chain

 Usage: pinman capture chain [OPTIONS] [ID]

 Show a capture's history chain (newest -> oldest).
 Select by positional ID or `--latest` (the newest backup capture).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture changes

 Usage: pinman capture changes [OPTIONS] [ID]

 Show a capture's changes vs its baseline (read-only; creates nothing).
 Folds the source capture's already-materialized rows against the reference —
 a pure read, no scan and no row created. Defaults to the head; select a
 stored capture by positional ID, or `--latest` for the newest non-head one.
 Omit `--reference` to diff against the source's own baseline; an explicit
 `--reference <id>` must be older than the source; `--no-reference` shows
 changes vs a bare baseline.
 Run `pinman capture refresh` first if you want the head's rows brought
 current before reading them.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                          Select the newest item    │
│                                                   (mutually exclusive with  │
│                                                   a positional ID/NAME).    │
│ --reference                    TEXT               Reference capture ID      │
│                                                   (must be older than the   │
│                                                   source). Omit to diff     │
│                                                   against the source's own  │
│                                                   baseline reference.       │
│ --no-reference                                    Do not use any reference  │
│                                                   capture.                  │
│ --compact/--no-compact                            Show each run of          │
│                                                   path-only folders above a │
│                                                   tracked item as one row.  │
│                                                   [default: compact]        │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture check

 Usage: pinman capture check [OPTIONS] [ID]

 Check a capture's record and item rows for internal contradictions.
 Defaults to the head. Select another by positional ID or `--latest`; use
 `--every-capture` for all of them (`--all` means the other axis on `capture
 verify`, so it is deliberately not spelled that way).
 Findings are hidden or shown by `persistence` and counted by `severity`, and
 the two are never crossed: a self-healing finding stays out of the default
 printout and still fails the run. Exit codes: 0 clean, 1 at or above
 `--fail-on`, 2 usage.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --every-capture                              Widen the tree checks to every │
│                                              capture, not just the head.    │
│                                              Never verifies bytes.          │
│ --stale                                      Print the self-healing         │
│                                              findings the default only      │
│                                              counts (display only).         │
│ --observe                                    Print the tier C observations. │
│ --fail-on                 [error|warn]       Exit 1 on any finding at or    │
│                                              above this severity. [default: │
│                                              error]                         │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture cleanup

 Usage: pinman capture cleanup [OPTIONS]

 Bulk-delete captures matching filters (chain-safe).
 Each matching capture is removed via `capture_delete` (oldest-first, so
 backed-up bytes merge cleanly into each successor). The head is never a
 candidate, nor are pending/in-progress captures.
 Default `--backup false` operates only on compares / checkpoints and never
 touches backups or savepoints (resume targets); pass `--backup true` to
 reclaim disk from old backups.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --source                  TEXT                     Filter by source: 'head' │
│                                                    (unfrozen, no source —   │
│                                                    not completed backups,   │
│                                                    which carry a freeze     │
│                                                    stamp), a capture ID, or │
│                                                    'any'. [default: any]    │
│ --reference               TEXT                     Filter by reference      │
│                                                    capture ID, or 'any'.    │
│                                                    [default: any]           │
│ --backup                  [true|false|any]         Filter by                │
│                                                    backed-up-bytes kind:    │
│                                                    'true'                   │
│                                                    (savepoints/backups      │
│                                                    only), 'false'           │
│                                                    (non-backed up only),    │
│                                                    'any' (no filter).       │
│                                                    [default: false]         │
│ --older-than              TEXT                     Only captures created    │
│                                                    before this age (e.g.    │
│                                                    90d, 6mo, 1y).           │
│ --status                  [completed|failed|cance  Filter by terminal       │
│                           lled|any]                status. 'any' =          │
│                                                    completed/failed/cancell │
│                                                    ed. [default: any]       │
│ --dry-run                                          Preview what would       │
│                                                    change without applying  │
│                                                    it.                      │
│ --force            -f                              Skip the confirmation    │
│                                                    prompt (and authorize    │
│                                                    the op when              │
│                                                    non-interactive).        │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture coverage

 Usage: pinman capture coverage [OPTIONS] [ID]

 Show a capture's coverage: its base floor plus every per-container extension.
 Defaults to the working capture (the head, else the newest); `--latest` is
 the newest capture of any kind, as `capture show`. A frozen savepoint carries
 extensions too (`capture broaden --item` can widen one in place from its
 stored bytes) — reach it by ID, since freezing spawns a newer head and
 `--latest` would return that instead.
 The base floor is the whole-capture extent (`capture create` sets it,
 `capture broaden` widens it). An extension is one container the user asked to
 see more of: it widens the floor THAT container enumerates its children at,
 and reaches no further down. Accumulated rows are what the capture holds
 without promising — every Refresh re-reads them, and a new capture clears
 them. Counterpart of the Explorer ribbon's Coverage group.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture create

 Usage: pinman capture create [OPTIONS]

 Freeze the head into a new capture (the kind is derived from the levers).
 Bare `capture create` makes a File Checkpoint (no copy, file-level, tracked
 items only). Add `--backup` for a Savepoint, `--granularity settings` for
 full per-setting detail, `--scope discovery` for a `+` kind — or use `--kind`
 as a shortcut. The resulting kind is printed on success.
 Examples:
     pinman capture create                          # File Checkpoint
     pinman capture create --backup                # Savepoint
     pinman capture create --kind "file savepoint"  # File Savepoint
     pinman capture create --kind savepoint --scope discovery   # Savepoint+

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --backup/--no-backup                                Back up a restorable    │
│                                                     copy of changed bytes   │
│                                                     (Savepoint). Off =      │
│                                                     metadata-only           │
│                                                     Checkpoint. [default:   │
│                                                     no-backup]              │
│ --granularity                  [file|settings]      Granularity: 'file'     │
│                                                     (file-level only — the  │
│                                                     'File' kinds) or        │
│                                                     'settings' (full        │
│                                                     per-setting detail).    │
│                                                     [default: file]         │
│ --scope                        [tracked|discovery]  Scope: 'tracked'        │
│                                                     (schema-tracked items   │
│                                                     only) or 'discovery'    │
│                                                     (also find untracked    │
│                                                     items — the '+' kinds). │
│                                                     [default: tracked]      │
│ --kind                         TEXT                 Preset the levers from  │
│                                                     a kind label (e.g.      │
│                                                     'checkpoint',           │
│                                                     'savepoint', 'file      │
│                                                     savepoint+'). Explicit  │
│                                                     levers override the     │
│                                                     preset.                 │
│ --title                        TEXT                 Title for the capture.  │
│ --note                         TEXT                 Journal annotation for  │
│                                                     this capture.           │
│ --zone                         TAG                  Zone tag (repeatable).  │
│ --software                     ID                   Software reference      │
│                                                     (repeatable).           │
│ --auto-associate/--no-                              Associate the entry     │
│ auto-associate                                      with the Zones and      │
│                                                     Software of changed     │
│                                                     tracked items.          │
│                                                     [default:               │
│                                                     auto-associate]         │
│ --resume                                            Resume the last         │
│                                                     incomplete savepoint    │
│                                                     (only valid with        │
│                                                     --backup).              │
│ --no-capacity-check                                 Skip the pre-flight     │
│                                                     disk space check        │
│                                                     (savepoints only).      │
│ --yes                   -y                          Skip the                │
│                                                     discovery-scope         │
│                                                     confirmation prompt     │
│                                                     (proceed even if        │
│                                                     large).                 │
│ --dry-run                                           Preview what would      │
│                                                     change without applying │
│                                                     it.                     │
│ --no-winreg-extract                                 Skip winreg extraction  │
│                                                     (use when already       │
│                                                     extracted for a         │
│                                                     discovery workflow).    │
│ --no-winrt-extract                                  Skip winrt extraction   │
│                                                     (use when already       │
│                                                     extracted for a         │
│                                                     discovery workflow).    │
│ --no-extract                                        Skip both winreg and    │
│                                                     winrt extraction.       │
│ --verbose/--quiet       -v/-q                       Echo/hide detailed      │
│                                                     output incl. progress   │
│                                                     logs (applies to the    │
│                                                     whole run; default      │
│                                                     quiet — PINMAN_VERBOSE  │
│                                                     env var sets the        │
│                                                     default).               │
│ --help                  -h,-?                       Show this message and   │
│                                                     exit.                   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture delete

 Usage: pinman capture delete [OPTIONS] [ID]

 Delete a capture (chain-safe).
 Select by positional ID or `--latest` (the newest non-head capture). Routes
 through `capture_delete`, which collapses the chain into the deleted
 capture's immediate successor (re-points references, merges backed-up bytes).
 Refuses the head.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                  Select the newest item (mutually exclusive with a │
│                           positional ID/NAME).                              │
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture dump

 Usage: pinman capture dump [OPTIONS] [ID]

 Dump a capture's items tree as JSON/YAML.
 Defaults to the working capture (the head, else the newest). Select a
 specific one by positional ID, or `--latest` for the newest — giving both is
 a usage error (no silent override).
 By default the tree is rendered with chain-back applied — rows reached via
 backup ancestors have their change_type/descendents_changes_count translated,
 matching what the API serves to the UI. Use --raw to dump the underlying DB
 rows verbatim.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --file                    FILE               Write the payload to this file │
│                                              as UTF-8 (default: stdout).    │
│ --raw                                        Dump raw DB rows without       │
│                                              chain-back translation         │
│                                              (chain-reached rows keep their │
│                                              stored change_type instead of  │
│                                              being translated to            │
│                                              UNCHANGED).                    │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture list

 Usage: pinman capture list [OPTIONS]

 List existing captures.
 `--backup true` narrows to captures that backed up their bytes (savepoints /
 backups) — the view the former `pinman backup list` provided; `--backup
 false` shows only non-backed up; the default `any` shows everything.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --backup                  [true|false|any]   Filter by backed-up-bytes      │
│                                              kind: 'true'                   │
│                                              (savepoints/backups only),     │
│                                              'false' (non-backed up only),  │
│                                              'any' (no filter). [default:   │
│                                              any]                           │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture maint

 Usage: pinman capture maint [OPTIONS] COMMAND [ARGS]...

 Capture maintenance: repair the head, clear the lock, prune incompletes, tune
 workers.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ clean        Delete incomplete (failed / interrupted) backup captures.      │
│ repair-head  Ensure a head exists (fail-safe).                              │
│ unlock       Clear abandoned lock metadata; a live operation keeps its      │
│              ownership.                                                     │
│ workers      Show or tune the threaded backup copy worker count.            │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture maint clean

 Usage: pinman capture maint clean [OPTIONS]

 Delete incomplete (failed / interrupted) backup captures.
 Default removes only the latest backup if it is incomplete; `--all` removes
 every incomplete backup. Refuses while a capture is running.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --all/--latest            Delete all incomplete backup captures (default:   │
│                           only the latest, if incomplete). [default:        │
│                           latest]                                           │
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture maint repair-head

 Usage: pinman capture maint repair-head [OPTIONS]

 Ensure a head exists (fail-safe).
 If a capture exists but no head does — a backup-only history, or a head
 removed out-of-band — spawn a fresh head over the latest frozen capture (no
 scan, inheriting its levers). Explore does this automatically on load; this
 exposes it explicitly. No-op when a head already exists; reports when there
 are no captures to reference.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture maint unlock

 Usage: pinman capture maint unlock [OPTIONS]

 Clear abandoned lock metadata; a live operation keeps its ownership.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture maint workers

 Usage: pinman capture maint workers [OPTIONS]

 Show or tune the threaded backup copy worker count.
 Default (no flags): show current config value and what auto would recommend,
 without writing.
 Use ``--auto`` to probe storage and persist the recommendation; use ``--set
 N`` to write a literal value; use ``--no-fs-scan`` to consider only the
 backups_root drive.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --auto                                  Probe storage and write the         │
│                                         recommended value to config.        │
│ --set                     INTEGER       Write a literal value to config     │
│                                         (skips probing).                    │
│ --no-fs-scan                            Skip the fs_root source probe;      │
│                                         consider only the backups_root      │
│                                         drive.                              │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture move

 Usage: pinman capture move [OPTIONS]

 Move/relocate backed up captures and update database references.
 Examples:
 # Repair mode: fix DB paths to match current config
 pinman capture move --repair


 # Move from current backups_root to new location   pinman capture move --to
 "D:/pinman-backups"
 # DB-only mode: update refs after manual file move   pinman capture move
 --from "C:/old" --to "C:/new" --db-only

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --to                         PATH  Destination backup root directory.       │
│ --from                       PATH  Source backup root directory. [default:  │
│                                    (current backups_root)]                  │
│ --repair                           Auto-detect and fix DB paths to match    │
│                                    current backups_root config.             │
│ --db-only                          Only update database (files already      │
│                                    moved manually).                         │
│ --dry-run                          Preview what would change without        │
│                                    applying it.                             │
│ --force               -f           Skip the confirmation prompt (and        │
│                                    authorize the op when non-interactive).  │
│ --verify/--no-verify               Verify files after copy (when moving     │
│                                    files).                                  │
│ --keep-source                      Don't delete source after successful     │
│                                    move.                                    │
│ --no-update-config                 Don't update backups_root in config      │
│                                    after success.                           │
│ --verbose/--quiet     -v/-q        Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│ --help                -h,-?        Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture refresh

 Usage: pinman capture refresh [OPTIONS]

 Refresh the head — re-read live values for its existing coverage.
 Lever-preserving and coverage-wide: re-scans at the head's own recorded floor
 (scope and granularity unchanged — the server reads them from the capture, no
 flags to get wrong), then value-refreshes coverage outside the floor
 (lazy-expanded subtrees, broadened slices). Never adds or removes coverage,
 never changes the floor or the kind label. UI counterpart of the Explore
 toolbar's Refresh (API `POST /captures/{id}/refresh`); run synchronously
 here.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --no-winreg-extract                            Skip winreg extraction (use  │
│                                                when already extracted)      │
│ --no-winrt-extract                             Skip winrt extraction (use   │
│                                                when already extracted)      │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture restore

 Usage: pinman capture restore [OPTIONS] CAPTURE_ID [LOCATIONS]...

 Restore LOCATIONS as capture CAPTURE_ID recorded them; its files when none
 are named.
 A file is replaced only when a Savepoint holds it as it is now, so the
 restore can be undone by restoring that Savepoint. `--take-savepoint` takes
 one first; `--overwrite-unsaved` replaces them anyway.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  CAPTURE_ID  INTEGER  [required]                                          │
│    LOCATIONS   TEXT                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --preview                                      Show what would change;      │
│                                                write nothing.               │
│ --take-savepoint                               Take a Savepoint first, so   │
│                                                what this changes can be put │
│                                                back.                        │
│ --overwrite-unsaved                            Change files even when no    │
│                                                Savepoint holds them as they │
│                                                are now.                     │
│ --registry                                     Whole capture: restore its   │
│                                                registry too.                │
│ --windows-settings                             Whole capture: restore its   │
│                                                Windows settings too.        │
│ --allow-writes                                 Write to the machine even    │
│                                                though machine_readonly is   │
│                                                enabled.                     │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture show

 Usage: pinman capture show [OPTIONS] [ID]

 Show a capture with its hierarchical items tree.
 Defaults to the working capture (the head, else the newest). Select a
 specific one by positional ID, or `--latest` for the newest.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                              Select the newest     │
│                                                       item (mutually        │
│                                                       exclusive with a      │
│                                                       positional ID/NAME).  │
│ --all                                                 Show all items        │
│ --changes                                             Show changed items    │
│                                                       and unresolved        │
│                                                       read/comparison gaps  │
│                                                       (default)             │
│ --tracked                                             Only tracked items    │
│ --only                         [files|data|winreg|wi  Show only items of    │
│                                nrt]                   this category         │
│ --zones                        TEXT                   Filter by zones       │
│                                                       (comma-separated)     │
│ --search                       TEXT                   Search in             │
│                                                       selector/location     │
│                                                       text                  │
│ --limit                        INTEGER                Max items to display  │
│ --page/--no-page                                      Enable paging         │
│ --compact/--no-compact                                Show each run of      │
│                                                       path-only folders     │
│                                                       above a tracked item  │
│                                                       as one row. [default: │
│                                                       compact]              │
│ --output                -o     [human|json|yaml]      Output format (human  │
│                                                       | json | yaml).       │
│                                                       [default: human]      │
│ --verbose/--quiet       -v/-q                         Echo/hide detailed    │
│                                                       output incl. progress │
│                                                       logs (applies to the  │
│                                                       whole run; default    │
│                                                       quiet —               │
│                                                       PINMAN_VERBOSE env    │
│                                                       var sets the          │
│                                                       default).             │
│ --help                  -h,-?                         Show this message and │
│                                                       exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman capture verify

 Usage: pinman capture verify [OPTIONS] [ID]

 Verify the stored bytes of a backed up capture.
 Select by positional ID or `--latest` (the newest backup capture). Exits
 non-zero (1) when verification finds issues. For the capture's *record*
 rather than its bytes, see `pinman capture check`.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --all/--any                                  Verify all items (don't stop   │
│                                              at the first error).           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config

 Usage: pinman config [OPTIONS] COMMAND [ARGS]...

 Manage pinman app configuration settings.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Settings ──────────────────────────────────────────────────────────────────┐
│ list   List all configuration settings, by group.                           │
│ get    Get a specific configuration value.                                  │
│ set    Set a configuration value.                                           │
│ env    Show the current environment, config files, and database location.   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ show   Show one setting: its value, default, type and description.          │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config env

 Usage: pinman config env [OPTIONS]

 Show the current environment, config files, and database location.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config get

 Usage: pinman config get [OPTIONS] KEY

 Get a specific configuration value.
 Unknown keys raise (exit 1) with the list of valid keys.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  KEY  TEXT  [required]                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config list

 Usage: pinman config list [OPTIONS]

 List all configuration settings, by group.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config set

 Usage: pinman config set [OPTIONS] KEY VALUE

 Set a configuration value.
 ``set_config`` validates the key (unknown → exit 1) and coerces/validates the
 value per key (bad value → exit 1); it never silently accepts bad input.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  KEY    TEXT  [required]                                                  │
│ *  VALUE  TEXT  [required]                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman config show

 Usage: pinman config show [OPTIONS] KEY

 Show one setting: its value, default, type and description.
 Unknown keys raise (exit 1) with the list of valid keys.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  KEY  TEXT  [required]                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control

 Usage: pinman control [OPTIONS] COMMAND [ARGS]...

 Machine controls: display, audio, slideshow, inputs, message, mode.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Controls ──────────────────────────────────────────────────────────────────┐
│ show       Show current machine control settings (volume, brightness,       │
│            message, …).                                                     │
│ display    Get or set the display.                                          │
│ audio      Get or set machine audio.                                        │
│ slideshow  Get or set the attract-mode slideshow.                           │
│ inputs     Get or set the inputs lock (lock out the machine's physical      │
│            controls).                                                       │
│ message    Post, clear, or show the on-screen message.                      │
│ mode       Switch the machine mode, or list the modes this machine offers.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control audio

 Usage: pinman control audio [OPTIONS]

 Get or set machine audio.
 No options reads the current volume/mute; ``--volume N`` sets the level;
 ``--mute`` / ``--unmute`` sets mute. A set writes the operator kit's tracked
 ``rest:/audio`` items, as the Controls page does, and exits 1 on any refusal;
 a down audio server reports ``unavailable`` on a read.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --volume                  INTEGER RANGE            Set output volume 0–100  │
│                           [0<=x<=100]              (omit to read the        │
│                                                    current state).          │
│ --mute/--unmute                                    Mute or unmute audio     │
│                                                    output.                  │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control display

 Usage: pinman control display [OPTIONS]

 Get or set the display.
 No options reads brightness + ON/OFF; ``--brightness N`` sets the level;
 ``--on`` / ``--off`` / ``--toggle`` controls the blank (only one at a time).
 A down overlay server fails a set (exit 1) but reports ``unavailable`` on a
 read.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --brightness              INTEGER RANGE            Set display brightness   │
│                           [0<=x<=100]              0–100 (omit to read the  │
│                                                    current state).          │
│ --on                                               Turn the display ON      │
│                                                    (unblank).               │
│ --off                                              Turn the display OFF     │
│                                                    (blank).                 │
│ --toggle                                           Toggle the display       │
│                                                    ON/OFF.                  │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control inputs

 Usage: pinman control inputs [OPTIONS]

 Get or set the inputs lock (lock out the machine's physical controls).
 No option reads the current lock state; ``--lock`` / ``--unlock`` sets it. A
 down inputs server fails a set (exit 1) but reports ``unavailable`` on a
 read.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --lock/--unlock                              Lock or unlock the machine's   │
│                                              physical inputs.               │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control message

 Usage: pinman control message [OPTIONS] [TEXT]

 Post, clear, or show the on-screen message.
 ``control message "<text>"`` posts; ``control message --clear`` stops it;
 bare ``control message`` shows the current message status.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TEXT  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --clear                                            Stop / clear the current │
│                                                    display message.         │
│ --mode                    [static|marquee|scrolli  How the message is       │
│                           ng]                      displayed. [default:     │
│                                                    static]                  │
│ --color                   TEXT                     Message color (hex).     │
│                                                    [default: #ffffff]       │
│ --duration                INTEGER                  Auto-clear after N       │
│                                                    seconds (omit or 0 =     │
│                                                    continuous).             │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control mode

 Usage: pinman control mode [OPTIONS] [NAME]

 Switch the machine mode, or list the modes this machine offers.
 Bare ``control mode`` lists them and marks the active one; ``control mode
 <name>`` switches. A mode spans many settings at once, so it applies the
 profile — which records history and an undo point, unlike the single-setting
 commands above.
 The active mode is the one whose settings all match, and there may be none:
 changing any single setting leaves the machine in no mode at all.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control show

 Usage: pinman control show [OPTIONS]

 Show current machine control settings (volume, brightness, message, …).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman control slideshow

 Usage: pinman control slideshow [OPTIONS]

 Get or set the attract-mode slideshow.
 No options reads the current state; ``--on`` starts it, ``--off`` stops it
 (only one at a time). ``--interruptable`` makes it dismissable by touching
 the machine. A down overlay server fails a set (exit 1) but reports
 ``unavailable`` on a read.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --on                                         Start the slideshow.           │
│ --off                                        Stop the slideshow.            │
│ --interruptable                              With --on: any key, click or   │
│                                              gamepad event dismisses it     │
│                                              (attract mode).                │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db

 Usage: pinman db [OPTIONS] COMMAND [ARGS]...

 Database-related commands.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inspect ───────────────────────────────────────────────────────────────────┐
│ show       Show the current project and DB URL.                             │
│ inspect    Inspect the database and show the tables with row counts.        │
│ current    Show current Alembic revision.                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Manage ────────────────────────────────────────────────────────────────────┐
│ create   Create database and tables (no migrations).                        │
│ reset    Delete all data from the database without dropping the file.       │
│ compact  Compact the database file (full VACUUM), reclaiming free space to  │
│          disk.                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ upgrade     Bring project databases up to this build's schema.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db compact

 Usage: pinman db compact [OPTIONS]

 Compact the database file (full VACUUM), reclaiming free space to disk.
 Rarely needed: deletes already return space automatically via incremental
 auto-vacuum. This is the manual deep-compact lever — it takes a brief
 database-wide lock and needs free disk roughly equal to the current file size
 while it rebuilds.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db create

 Usage: pinman db create [OPTIONS]

 Create database and tables (no migrations).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db current

 Usage: pinman db current [OPTIONS]

 Show current Alembic revision.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db inspect

 Usage: pinman db inspect [OPTIONS]

 Inspect the database and show the tables with row counts.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db reset

 Usage: pinman db reset [OPTIONS]

 Delete all data from the database without dropping the file.
 Destructive: confirms in a terminal, refuses non-interactively without
 ``--force`` (exit 2).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db show

 Usage: pinman db show [OPTIONS]

 Show the current project and DB URL.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman db upgrade

 Usage: pinman db upgrade [OPTIONS]

 Bring project databases up to this build's schema.
 Run after installing a newer Pinman: the installer does this for you, but a
 hub restored from backup, copied between machines, or left behind by a manual
 file swap needs it run by hand.
 Stops Pinman for the duration — migrating a SQLite database under a live API
 (and its scheduler) risks lock errors, and the pre-upgrade copy would be
 taken while something else is still writing.
 Idempotent — a project already at head is reported and skipped. Each database
 that IS migrated is copied to ``pinman.db.pre-<revision>`` first; there are
 no backwards migrations, so that copy is the way back.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --all-projects/--active-                            Migrate every project   │
│ only                                                in the hub (default),   │
│                                                     or only the active one. │
│ --force                   -f                        Skip the confirmation   │
│                                                     prompt (and authorize   │
│                                                     the op when             │
│                                                     non-interactive).       │
│ --output                  -o     [human|json|yaml]  Output format (human |  │
│                                                     json | yaml). [default: │
│                                                     human]                  │
│ --verbose/--quiet         -v/-q                     Echo/hide detailed      │
│                                                     output incl. progress   │
│                                                     logs (applies to the    │
│                                                     whole run; default      │
│                                                     quiet — PINMAN_VERBOSE  │
│                                                     env var sets the        │
│                                                     default).               │
│ --help                    -h,-?                     Show this message and   │
│                                                     exit.                   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device

 Usage: pinman device [OPTIONS] COMMAND [ARGS]...

 Manage devices: detection, inventory, assignment, bindings, software.
 Role definitions live under `pinman device role`; assignments use `pinman
 device assign --role`. Bindings and software links have their own nested
 groups.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Detection ─────────────────────────────────────────────────────────────────┐
│ detect  Scan hardware and update the device table.                          │
│ ghosts  Show USB devices that are known but no longer present (unplugged).  │
│ status  Check status of the active box's devices (presence, health, ports). │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inventory ─────────────────────────────────────────────────────────────────┐
│ list      List known devices.                                               │
│ show      Show detail for a single device by name or ID.                    │
│ add       Manually add a device (for non-auto-detected hardware).           │
│ remove    Remove a device by name or ID.                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Assignment ────────────────────────────────────────────────────────────────┐
│ assign     Assign a device to a box and/or set logical device role(s).      │
│ unassign   Unassign a device: remove from one box, or clear box/roles/both. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Sub-groups ────────────────────────────────────────────────────────────────┐
│ binding      Manage logical device bindings (role variables).               │
│ software     Manage software-catalog links for a device.                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ role     Manage schema-defined logical device roles.                        │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device add

 Usage: pinman device add [OPTIONS] NAME

 Manually add a device (for non-auto-detected hardware).
 Pre-declared displays should carry --edid so detection matches them on
 plug-in (flips detected=True) instead of creating a duplicate record.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --class                   [display|audio|usb|ot  Device class.           │
│                              her]                   [required]              │
│    --vid-pid                 TEXT                   USB VID:PID (e.g.       │
│                                                     1209:BADA).             │
│    --serial                  TEXT                   Serial number.          │
│    --edid                    TEXT                   Display MonitorDeviceID │
│                                                     (required for display   │
│                                                     re-match on plug-in).   │
│    --edid-serial             TEXT                   Per-unit EDID serial    │
│                                                     (0xFF descriptor).      │
│    --description             TEXT                   Device description.     │
│    --verbose/--quiet  -v/-q                         Echo/hide detailed      │
│                                                     output incl. progress   │
│                                                     logs (applies to the    │
│                                                     whole run; default      │
│                                                     quiet — PINMAN_VERBOSE  │
│                                                     env var sets the        │
│                                                     default).               │
│    --help             -h,-?                         Show this message and   │
│                                                     exit.                   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device assign

 Usage: pinman device assign [OPTIONS] NAME

 Assign a device to a box and/or set logical device role(s).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --box                     TEXT  Box name to assign to.                      │
│ --role                    TEXT  Logical device role (can repeat).           │
│ --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress    │
│                                 logs (applies to the whole run; default     │
│                                 quiet — PINMAN_VERBOSE env var sets the     │
│                                 default).                                   │
│ --help             -h,-?        Show this message and exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device binding

 Usage: pinman device binding [OPTIONS] COMMAND [ARGS]...

 Manage logical device bindings (role variables).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ clear    Remove a binding by key.                                           │
│ list     List all active bindings (auto-generated and manual).              │
│ set      Create or update a manual binding.                                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device binding clear

 Usage: pinman device binding clear [OPTIONS] KEY

 Remove a binding by key.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  KEY  TEXT  [required]                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device binding list

 Usage: pinman device binding list [OPTIONS]

 List all active bindings (auto-generated and manual).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device binding set

 Usage: pinman device binding set [OPTIONS] KEY VALUE

 Create or update a manual binding.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  KEY    TEXT  [required]                                                  │
│ *  VALUE  TEXT  [required]                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --description             TEXT  Binding description.                        │
│ --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress    │
│                                 logs (applies to the whole run; default     │
│                                 quiet — PINMAN_VERBOSE env var sets the     │
│                                 default).                                   │
│ --help             -h,-?        Show this message and exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device detect

 Usage: pinman device detect [OPTIONS]

 Scan hardware and update the device table.
 Detects displays and audio devices (via WinRT) and USB HID devices (via
 pywinusb), reconciling them against the device table.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --changes                                    Only show new and gone         │
│                                              devices.                       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device ghosts

 Usage: pinman device ghosts [OPTIONS]

 Show USB devices that are known but no longer present (unplugged).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device list

 Usage: pinman device list [OPTIONS]

 List known devices.
 Reads the DB — the source of truth, which may have drifted from the live
 hardware. Pass --refresh to rescan hardware (a quiet detect) first.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --class                   [display|audio|usb|othe  Filter by device class.  │
│                           r]                                                │
│ --detected/--all                                   Filter by detection      │
│                                                    status.                  │
│ --refresh                                          Rescan live hardware     │
│                                                    before listing           │
│                                                    (persisted). Default     │
│                                                    reads the DB (cached).   │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device remove

 Usage: pinman device remove [OPTIONS] NAME

 Remove a device by name or ID.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role

 Usage: pinman device role [OPTIONS] COMMAND [ARGS]...

 Manage schema-defined logical device roles.
 These commands author role definitions. Use `device assign --role` to
 associate a detected device with one of them.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ create  Create a validated logical role definition.                         │
│ delete  Delete a role and clean its assignments and role-prefixed bindings. │
│ edit    Edit role fields without changing assignments or bindings.          │
│ import  Import a top-level `device_roles:` list from YAML.                  │
│ list    List role definitions (not physical-device assignments).            │
│ show    Show one role definition and its authored zones.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role create

 Usage: pinman device role create [OPTIONS] NAME

 Create a validated logical role definition.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --device-class            TEXT               Hardware class, such as     │
│                                                 display or audio.           │
│                                                 [required]                  │
│    --zone                    TEXT               Defined Zone tag            │
│                                                 (repeatable).               │
│    --label                   TEXT               Human-readable role label.  │
│    --dry-run                                    Preview what would change   │
│                                                 without applying it.        │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role delete

 Usage: pinman device role delete [OPTIONS] NAME

 Delete a role and clean its assignments and role-prefixed bindings.
 Dry-run reports those impacts. A real deletion requires confirmation or
 `--force` and removes only the role references, not devices or Zone tags.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role edit

 Usage: pinman device role edit [OPTIONS] NAME

 Edit role fields without changing assignments or bindings.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --device-class            TEXT               Replace the hardware class.    │
│ --zone                    TEXT               Replace zones (repeatable).    │
│ --clear-zones                                Remove all zones from the      │
│                                              definition.                    │
│ --label                   TEXT               Replace the human-readable     │
│                                              label.                         │
│ --clear-label                                Remove the label.              │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role import

 Usage: pinman device role import [OPTIONS] FILE

 Import a top-level `device_roles:` list from YAML.
 Merge is the default. `--replace` synchronizes the complete role catalog;
 removals require confirmation or `--force` and clean active references.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FILE  FILE  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --replace                                    Also remove definitions absent │
│                                              from FILE.                     │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role list

 Usage: pinman device role list [OPTIONS]

 List role definitions (not physical-device assignments).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device role show

 Usage: pinman device role show [OPTIONS] NAME

 Show one role definition and its authored zones.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device show

 Usage: pinman device show [OPTIONS] NAME

 Show detail for a single device by name or ID.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device software

 Usage: pinman device software [OPTIONS] COMMAND [ARGS]...

 Manage software-catalog links for a device.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ add       Link a software catalog entry to a device.                        │
│ list      List class-default and instance software for a device.            │
│ remove    Remove a software link from a device.                             │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device software add

 Usage: pinman device software add [OPTIONS] NAME SOFTWARE_ID

 Link a software catalog entry to a device.
 NAME is the device name or numeric ID; SOFTWARE_ID is the catalog entry ID
 (e.g. 'nvidia_app').

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME         TEXT  [required]                                            │
│ *  SOFTWARE_ID  TEXT  [required]                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device software list

 Usage: pinman device software list [OPTIONS] NAME

 List class-default and instance software for a device.
 The full catalog is available via `pinman software list`.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device software remove

 Usage: pinman device software remove [OPTIONS] NAME SOFTWARE_ID

 Remove a software link from a device.
 NAME is the device name or numeric ID; SOFTWARE_ID is the catalog entry ID.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME         TEXT  [required]                                            │
│ *  SOFTWARE_ID  TEXT  [required]                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device status

 Usage: pinman device status [OPTIONS]

 Check status of the active box's devices (presence, health, ports).
 With --refresh (default), re-checks the active box's devices against live
 hardware and persists the result, so an unplugged device is noticed. Use
 'pinman device detect' for system-wide discovery of new/removed hardware.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --refresh/--no-refresh                            Re-check the active box's │
│                                                   devices against live      │
│                                                   hardware first (default), │
│                                                   or report from the DB     │
│                                                   only.                     │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman device unassign

 Usage: pinman device unassign [OPTIONS] NAME

 Unassign a device: remove from one box, or clear box/roles/both.
 Examples:
 pinman device unassign "Dell Monitor"
 pinman device unassign "Dell Monitor" --box Backbox
 pinman device unassign "Dell Monitor" --keep-box
 pinman device unassign "Dell Monitor" --keep-role

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --box                     TEXT  Remove from just this one box (other box    │
│                                 memberships are kept).                      │
│ --keep-box                      Clear roles only (keep box membership).     │
│ --keep-role                     Remove from box only (keep roles +          │
│                                 bindings).                                  │
│ --force            -f           Skip the confirmation prompt (and authorize │
│                                 the op when non-interactive).               │
│ --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress    │
│                                 logs (applies to the whole run; default     │
│                                 quiet — PINMAN_VERBOSE env var sets the     │
│                                 default).                                   │
│ --help             -h,-?        Show this message and exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore

 Usage: pinman explore [OPTIONS] COMMAND [ARGS]...

 Browse, inspect, diff, tag, and manage tracked items (the UI's Explore page).
 Reads the head by default; pass --id/--latest on any verb to browse a
 specific capture instead. The lifecycle verbs (track/untrack/edit/convert)
 mutate the schema (the tracked structure).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Browse ────────────────────────────────────────────────────────────────────┐
│ list  Browse captured items with filters (the Explore page's item browser). │
│ show  Inspect one item by location (the Explore detail drawer).             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inspect ───────────────────────────────────────────────────────────────────┐
│ diff  Compare two items by location within one capture (A = source, B =     │
│       reference).                                                           │
│ tag   Add or remove zone tags on items by location (bulk).                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Tracked structure ─────────────────────────────────────────────────────────┐
│ track    Track an item — create a schema item so it enters the tracked set. │
│ untrack  Untrack an item — remove its schema item (it leaves the tracked    │
│          set).                                                              │
│ edit     Edit a tracked item's metadata (label, description, zones,         │
│          software refs).                                                    │
│ convert  Convert a tracked section schema to a table (the UI's "Convert to  │
│          table").                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ expand   Expand an item one level — materialize its direct children (the    │
│          Explore tree chevron).                                             │
│ refresh  Refresh this level of the head: a container and its immediate      │
│          members.                                                           │
│ set      Write one item's value to the machine (the UI's inline value       │
│          edit).                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore convert

 Usage: pinman explore convert [OPTIONS] LOCATION

 Convert a tracked section schema to a table (the UI's "Convert to table").
 Structural: rewrites the saved schema's type and moves its children under a
 {{KEY}} row placeholder, retaining recorded capture facts. Only valid for
 ini_section / xml_section items. Create a Capture after converting to
 materialize the new table's rows.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER            Browse a specific capture by   │
│                                              ID (default: the head).        │
│ --latest                                     Browse the newest capture      │
│                                              (mutually exclusive with       │
│                                              --id).                         │
│ --key                     TEXT               Binding key name for the       │
│                                              table. [default: KEY]          │
│ --pattern                 TEXT               Section-match pattern for the  │
│                                              table rows. [default: *]       │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore diff

 Usage: pinman explore diff [OPTIONS] LOCATION_A LOCATION_B

 Compare two items by location within one capture (A = source, B = reference).
 Folds A-vs-B with the same engine the `capture changes` derive uses, so
 containers show their changed subtree and leaves show a value/size delta.
 Both locations are resolved in the same capture (default: the head).
 Example:
     pinman explore diff "fs:C:/a/config.ini" "fs:C:/b/config.ini"

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION_A  TEXT  [required]                                             │
│ *  LOCATION_B  TEXT  [required]                                             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                           INTEGER            Browse a specific capture │
│                                                   by ID (default: the       │
│                                                   head).                    │
│ --latest                                          Browse the newest capture │
│                                                   (mutually exclusive with  │
│                                                   --id).                    │
│ --limit                        INTEGER            Max folded nodes.         │
│                                                   [default: 500]            │
│ --compact/--no-compact                            Show each run of          │
│                                                   path-only folders above a │
│                                                   tracked item as one row.  │
│                                                   [default: compact]        │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore edit

 Usage: pinman explore edit [OPTIONS] LOCATION

 Edit a tracked item's metadata (label, description, zones, software refs).
 Updates the schema item (the UI's edit-metadata) and its linked instances.
 Tag changes can propagate with --propagate. Changing a whole file's
 interpretation requires Refresh or a new Capture to adopt its coverage.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER              Browse a specific capture by │
│                                                ID (default: the head).      │
│ --latest                                       Browse the newest capture    │
│                                                (mutually exclusive with     │
│                                                --id).                       │
│ --itemtype                TEXT                 Change a whole file's        │
│                                                supported interpretation.    │
│ --label                   TEXT                 New label.                   │
│ --description             TEXT                 New description.             │
│ --schema-props            JSON                 Replace schema rules with a  │
│                                                JSON object.                 │
│ --zone                    TAG                  Replace zone tags            │
│                                                (repeatable).                │
│ --software                ID                   Replace software refs        │
│                                                (repeatable).                │
│ --propagate               [none|children|all]  Propagate Zone and Software  │
│                                                association changes to       │
│                                                descendants. [default: none] │
│ --output           -o     [human|json|yaml]    Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet  -v/-q                       Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help             -h,-?                       Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore expand

 Usage: pinman explore expand [OPTIONS] LOCATION

 Expand an item one level — materialize its direct children (the Explore tree
 chevron).
 Against the head (default), children materialize at the capture floor from
 live data (fs) or the head's existing extract (winreg/winrt), copying the row
 up from a frozen ancestor when needed. Against a frozen capture
 (--id/--latest), a stored-bytes row expands in place, snapshot-age.
 A cold tracked winreg hive extracts that ONE hive's tracked keys on demand
 first (what the UI's `winreg_extract` dispatch runs as a polled task) rather
 than dead-ending on "run Refresh"; here it runs synchronously.
 Example:
     pinman explore expand "fs:/C/MyApp/settings.ini#Display"

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER            Browse a specific capture by   │
│                                              ID (default: the head).        │
│ --latest                                     Browse the newest capture      │
│                                              (mutually exclusive with       │
│                                              --id).                         │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore list

 Usage: pinman explore list [OPTIONS]

 Browse captured items with filters (the Explore page's item browser).
 Source defaults to the head; use --id/--latest to browse a specific capture.
 With no --changed, all items are shown (capped by --limit).
 --at LOCATION re-roots the tree at one container (the API's `GET
 /captures/{id}?location=...`). This is how below-floor and chain-shared rows
 become visible: a head's whole-tree read is bounded to its own
 granularity/scope floor, so borrowed deeper rows are dropped — re-rooting at
 the container resolves the floor from the capture that owns the row instead.
 Its children are listed, as the capture root's are.
 Example:
     pinman explore list --at "winrt:/Sound"

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                           INTEGER            Browse a specific capture │
│                                                   by ID (default: the       │
│                                                   head).                    │
│ --latest                                          Browse the newest capture │
│                                                   (mutually exclusive with  │
│                                                   --id).                    │
│ --at                           LOCATION           Re-root the tree at one   │
│                                                   container (the Explore    │
│                                                   page's drill-in). Reaches │
│                                                   rows the whole-tree view  │
│                                                   bounds out at the capture │
│                                                   floor.                    │
│ --realm                        TEXT               Filter by realm (fs,      │
│                                                   winreg, winrt, bundle,    │
│                                                   rest). Repeatable.        │
│ --tracked                                         Only tracked              │
│                                                   (schema-bound) items.     │
│ --changed                                         Changed items and         │
│                                                   unresolved                │
│                                                   read/comparison gaps.     │
│ --software                     TEXT               Filter by Software entry  │
│                                                   or group ID (group prefix │
│                                                   matches). Repeatable.     │
│ --search                       TEXT               Case-insensitive match in │
│                                                   selector or location.     │
│ --view                         [tree|flat|table]  Human render style        │
│                                                   (machine output is always │
│                                                   the structured tree).     │
│                                                   [default: tree]           │
│ --detail                       [simple|advanced]  Detail level (advanced    │
│                                                   shows more per item in    │
│                                                   tree view). [default:     │
│                                                   simple]                   │
│ --depth                        INTEGER            Limit displayed items to  │
│                                                   this many levels deep     │
│                                                   (presentation only; all   │
│                                                   views).                   │
│ --compact/--no-compact                            Show each run of          │
│                                                   path-only folders above a │
│                                                   tracked item as one row.  │
│                                                   [default: compact]        │
│ --limit                        INTEGER            Max items to return.      │
│                                                   [default: 500]            │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore refresh

 Usage: pinman explore refresh [OPTIONS] LOCATION

 Refresh this level of the head: a container and its immediate members.
 Deeper recorded contents retain their previous values until explicitly
 refreshed. Use `capture refresh` to refresh the whole head.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore set

 Usage: pinman explore set [OPTIONS] LOCATION VALUE

 Write one item's value to the machine (the UI's inline value edit).
 Distinct from `explore edit`, which changes an item's METADATA. This changes
 the setting itself, in the property's own stored units — volume is 0.0-1.0,
 not 0-100.
 Only a TRACKED location can be written — the schema is the gate, so a setting
 Pinman merely discovered is refused until `explore track` declares it. Also
 gated by `machine_readonly`; `--allow-writes` authorizes this one invocation.
 With `require_savepoint` on, a file no Savepoint holds is refused:
 `--take-savepoint` takes one first, `--overwrite-unsaved` writes anyway.
 Exits non-zero when the write is refused.
 Put `--` before a value that starts with a dash, or it is read as an option.
 Option parsing stays strict on purpose: silently accepting a mistyped flag as
 the value would write it to the machine.
 Examples:
     pinman explore set "fs:/C/MyApp/settings.ini#Display/Width" 3840
     pinman explore set -- "fs:/C/MyApp/settings.ini#Display/Offset" -1

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
│ *  VALUE     TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --allow-writes                                 Write to the machine even    │
│                                                though machine_readonly is   │
│                                                enabled.                     │
│ --take-savepoint                               Take a Savepoint first, so   │
│                                                what this changes can be put │
│                                                back.                        │
│ --overwrite-unsaved                            Change files even when no    │
│                                                Savepoint holds them as they │
│                                                are now.                     │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore show

 Usage: pinman explore show [OPTIONS] LOCATION

 Inspect one item by location (the Explore detail drawer).
 Also reports which broaden axes this row can serve and at what cost — the
 signal behind the Explore page's per-row lever toggles. An axis is omitted
 when the floor doesn't narrow that lever at this row (nothing to widen, or a
 broaden already widened it here); an unavailable one carries the reason.
 Widen it with `pinman capture broaden --item LOCATION`.
 Example:
     pinman explore show "fs:C:/MyApp/settings.ini"

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER            Browse a specific capture by   │
│                                              ID (default: the head).        │
│ --latest                                     Browse the newest capture      │
│                                              (mutually exclusive with       │
│                                              --id).                         │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore tag

 Usage: pinman explore tag [OPTIONS] LOCATION...

 Add or remove zone tags on items by location (bulk).
 Applies EXISTING zone-tag definitions to tracked items — this is tag
 APPLICATION, distinct from `pinman tag` (which manages tag DEFINITIONS).
 Items must be tracked (schema-bound). Undefined tags are rejected on --add;
 --remove strips a tag regardless (so orphaned tags can be cleaned up).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATIONS  LOCATION...  [required]                                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --add                     TAG                  Zone tag to add. Repeatable. │
│ --remove                  TAG                  Zone tag to remove.          │
│                                                Repeatable.                  │
│ --id                      INTEGER              Browse a specific capture by │
│                                                ID (default: the head).      │
│ --latest                                       Browse the newest capture    │
│                                                (mutually exclusive with     │
│                                                --id).                       │
│ --propagate               [none|children|all]  Also apply the change to     │
│                                                descendants. [default: none] │
│ --output           -o     [human|json|yaml]    Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet  -v/-q                       Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help             -h,-?                       Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore track

 Usage: pinman explore track [OPTIONS] LOCATION

 Track an item — create a schema item so it enters the tracked set.
 Additive (the UI's Explore/Schema "Track"): creates a schema item from the
 item at LOCATION, backfilling untracked parent containers. Named INI sections
 track one setting by default; --selector requests an explicit rule. Run
 `pinman capture refresh` to re-materialize the tree against the new schema.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER            Browse a specific capture by   │
│                                              ID (default: the head).        │
│ --latest                                     Browse the newest capture      │
│                                              (mutually exclusive with       │
│                                              --id).                         │
│ --selector                TEXT               Target selector; use */KEY for │
│                                              a property template.           │
│ --itemtype                TEXT               Interpret the target as this   │
│                                              supported item type.           │
│ --label                   TEXT               Label for the tracked schema   │
│                                              item.                          │
│ --description             TEXT               Description for the tracked    │
│                                              schema item.                   │
│ --schema-props            JSON               Full schema rules as a JSON    │
│                                              object.                        │
│ --zone                    TAG                Zone tag to set (repeatable).  │
│ --software                ID                 Software reference             │
│                                              (repeatable).                  │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman explore untrack

 Usage: pinman explore untrack [OPTIONS] LOCATION

 Untrack an item — remove its schema item (it leaves the tracked set).
 Destructive (the UI's "Untrack"): deletes the schema item and orphans its
 instances. Blocked if the schema has tracked children — untrack those first.
 After untracking, run `pinman capture refresh` to re-materialize the tree.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id                      INTEGER            Browse a specific capture by   │
│                                              ID (default: the head).        │
│ --latest                                     Browse the newest capture      │
│                                              (mutually exclusive with       │
│                                              --id).                         │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman file

 Usage: pinman file [OPTIONS] COMMAND [ARGS]...

 File formats Pinman reads and writes.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inspect ───────────────────────────────────────────────────────────────────┐
│ list    File formats Pinman supports, from the live declarations.           │
│ show    Everything Pinman declares about one file format.                   │
│ check   Can Pinman write this file? Runs the real writer against a copy.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman file check

 Usage: pinman file check [OPTIONS] [PATH]

 Can Pinman write this file? Runs the real writer against a copy.
 Your file is never touched: its bytes are copied to a temporary directory and
 every write happens there. Reports two things that are not the same — what
 this release lets you do with the file, and what the writer does to it when
 measured. `--schema` checks every file your schema declares, as declared.
 Exit codes: 0 clean, 1 at or above `--fail-on`, 2 usage.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ PATH  FILE                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --schema                                     Check every file the active    │
│                                              project's schema declares,     │
│                                              instead of one file.           │
│ --item                    SELECTOR           With --schema, check only the  │
│                                              declared item with this        │
│                                              selector.                      │
│ --as                      FORMAT             Read the file as this format.  │
│                                              Required when its extension    │
│                                              names several.                 │
│ --prop                    KEY=VALUE          A schema property the format   │
│                                              needs, e.g. primary_key=ID.    │
│                                              Repeatable.                    │
│ --fail-on                 [error|warn]       Exit 1 on any finding at or    │
│                                              above this severity. [default: │
│                                              error]                         │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman file list

 Usage: pinman file list [OPTIONS]

 File formats Pinman supports, from the live declarations.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --domain                  [platform|pinball|all]  Only formats for this     │
│                                                   domain, or all. [default: │
│                                                   platform]                 │
│ --all                                             Every domain. Not with    │
│                                                   --domain.                 │
│ --wip                                             Also list                 │
│                                                   work-in-progress formats  │
│                                                   this release does not     │
│                                                   support yet.              │
│ --output           -o     [human|json|yaml]       Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet  -v/-q                          Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help             -h,-?                          Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman file show

 Usage: pinman file show [OPTIONS] FORMAT

 Everything Pinman declares about one file format.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FMT  FORMAT  [required]                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal

 Usage: pinman journal [OPTIONS] COMMAND [ARGS]...

 Journal entries: log, inspect, edit, and share.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Entries ───────────────────────────────────────────────────────────────────┐
│ list    List recent journal entries (newest first).                         │
│ show    Show one journal entry's detail.                                    │
│ create  Create a journal entry, optionally with a linked capture.           │
│ edit    Edit a journal entry's title, note, zones or software.              │
│ delete  Delete a journal entry, and with `--with-capture` its linked        │
│         capture.                                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Export ────────────────────────────────────────────────────────────────────┐
│ share     Export journal entries as a markdown report.                      │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal create

 Usage: pinman journal create [OPTIONS]

 Create a journal entry, optionally with a linked capture.
 Use `--capture` to run a capture and link it to the entry. The capture levers
 (`--backup/--no-backup`, `--granularity file|settings`, `--scope
 tracked|discovery`) apply only with `--capture`; this is a capture-creating
 entry point, so it takes the full shared lever decorator.
 `--zone`/`--software` must be defined in the schema; `--auto-associate`
 (default) adds the Zones and Software references of the tracked items the
 capture changed.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --title                      TEXT                 Short title            │
│                                                      (required). [required] │
│    --note                       TEXT                 Optional note /        │
│                                                      annotation.            │
│    --zone                       TAG                  Zone tag (repeatable). │
│    --software                   ID                   Software reference     │
│                                                      (repeatable).          │
│    --auto-associate/--n                              Associate the entry    │
│    o-auto-associate                                  with the Zones and     │
│                                                      Software of changed    │
│                                                      tracked items.         │
│                                                      [default:              │
│                                                      auto-associate]        │
│    --capture                                         Run a capture and link │
│                                                      it to this entry.      │
│    --backup/--no-backup                              Back up a restorable   │
│                                                      copy of changed bytes  │
│                                                      (Savepoint). Off =     │
│                                                      metadata-only          │
│                                                      Checkpoint. [default:  │
│                                                      no-backup]             │
│    --granularity                [file|settings]      Granularity: 'file'    │
│                                                      (file-level only — the │
│                                                      'File' kinds) or       │
│                                                      'settings' (full       │
│                                                      per-setting detail).   │
│                                                      [default: file]        │
│    --scope                      [tracked|discovery]  Scope: 'tracked'       │
│                                                      (schema-tracked items  │
│                                                      only) or 'discovery'   │
│                                                      (also find untracked   │
│                                                      items — the '+'        │
│                                                      kinds). [default:      │
│                                                      tracked]               │
│    --output              -o     [human|json|yaml]    Output format (human | │
│                                                      json | yaml).          │
│                                                      [default: human]       │
│    --verbose/--quiet     -v/-q                       Echo/hide detailed     │
│                                                      output incl. progress  │
│                                                      logs (applies to the   │
│                                                      whole run; default     │
│                                                      quiet — PINMAN_VERBOSE │
│                                                      env var sets the       │
│                                                      default).              │
│    --help                -h,-?                       Show this message and  │
│                                                      exit.                  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal delete

 Usage: pinman journal delete [OPTIONS] [ID]

 Delete a journal entry, and with `--with-capture` its linked capture.
 Select by positional ID or `--latest` (the newest entry).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                  Select the newest item (mutually exclusive with a │
│                           positional ID/NAME).                              │
│ --with-capture            Also delete the entry's linked capture            │
│                           (chain-safe, like `capture delete`).              │
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal edit

 Usage: pinman journal edit [OPTIONS] [ID]

 Edit a journal entry's title, note, zones or software.
 Select by positional ID or `--latest` (the newest entry). Only the fields you
 pass change: `--zone` replaces the zones, `--software` replaces the software,
 `--clear-associations` empties both. Values must be defined in the schema.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                        Select the newest item      │
│                                                 (mutually exclusive with a  │
│                                                 positional ID/NAME).        │
│ --title                      TEXT               New title.                  │
│ --note                       TEXT               New note / annotation       │
│                                                 (replaces existing).        │
│ --zone                       TAG                Replace the zones with      │
│                                                 these (repeatable). Omit to │
│                                                 leave zones unchanged.      │
│ --software                   ID                 Replace the software with   │
│                                                 these (repeatable). Omit to │
│                                                 leave software unchanged.   │
│ --clear-associations                            Remove all zones and        │
│                                                 software (not with          │
│                                                 --zone/--software).         │
│ --output              -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│ --verbose/--quiet     -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│ --help                -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal list

 Usage: pinman journal list [OPTIONS]

 List recent journal entries (newest first).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --source                  [note|system]      Filter by entry source.        │
│ --search                  TEXT               Text search in title / note.   │
│ --from                    [%Y-%m-%d]         First local day (YYYY-MM-DD).  │
│ --to                      [%Y-%m-%d]         Last local day (YYYY-MM-DD).   │
│ --zone                    TAG                Only entries with this zone    │
│                                              (repeatable; any match; a      │
│                                              category matches its           │
│                                              children).                     │
│ --software                ID                 Only entries with this         │
│                                              software (repeatable; any      │
│                                              match).                        │
│ --limit                   INTEGER            Max entries to show. [default: │
│                                              20]                            │
│ --offset                  INTEGER            Pagination offset. [default:   │
│                                              0]                             │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal share

 Usage: pinman journal share [OPTIONS] [ENTRY_IDS]...

 Export journal entries as a markdown report.
 Pass one or more entry IDs to export exactly those (selection scope), which
 ignores the filters. Otherwise the current filters apply (`--source`,
 `--search`, `--from`/`--to`, `--zone`, `--software`); with none set, the
 entire journal is exported. Markdown goes to stdout (pipeable) by default, or
 to `--file` as UTF-8.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ ENTRY_IDS  INTEGER                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --source                  TEXT        Filter by entry source.               │
│ --search                  TEXT        Text search in title / note.          │
│ --from                    [%Y-%m-%d]  First local day (YYYY-MM-DD).         │
│ --to                      [%Y-%m-%d]  Last local day (YYYY-MM-DD).          │
│ --zone                    TAG         Only entries with this zone           │
│                                       (repeatable; any match; a category    │
│                                       matches its children).                │
│ --software                ID          Only entries with this software       │
│                                       (repeatable; any match).              │
│ --file                    FILE        Write the payload to this file as     │
│                                       UTF-8 (default: stdout).              │
│ --verbose/--quiet  -v/-q              Echo/hide detailed output incl.       │
│                                       progress logs (applies to the whole   │
│                                       run; default quiet — PINMAN_VERBOSE   │
│                                       env var sets the default).            │
│ --help             -h,-?              Show this message and exit.           │
└─────────────────────────────────────────────────────────────────────────────┘

pinman journal show

 Usage: pinman journal show [OPTIONS] [ID]

 Show one journal entry's detail.
 Select by positional ID or `--latest` (the newest entry).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET  [ID]                                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest                                     Select the newest item         │
│                                              (mutually exclusive with a     │
│                                              positional ID/NAME).           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit

 Usage: pinman kit [OPTIONS] COMMAND [ARGS]...

 Manage content kits (author, install, import into a project).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Library ───────────────────────────────────────────────────────────────────┐
│ list       List installed kits and the kits the active project has added.   │
│ install    Install a kit from a .zip (or directory) onto this machine's hub │
│            store.                                                           │
│ uninstall  Uninstall a kit from this machine's hub store (inverse of        │
│            install).                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Project ───────────────────────────────────────────────────────────────────┐
│ import  Import an installed kit into the active project (schema merged;     │
│         profiles; requires first).                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Authoring ─────────────────────────────────────────────────────────────────┐
│ create  Scaffold an empty kit skeleton NAME/ for an author to fill.         │
│ build   Build kit NAME into a distributable <name>-kit-<version>.zip.       │
│ check   Validate a project's kit membership (resolvable, requires, drift,   │
│         collisions).                                                        │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit build

 Usage: pinman kit build [OPTIONS] NAME

 Build kit NAME into a distributable <name>-kit-<version>.zip.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --version                 TEXT               Override the built artifact's  │
│                                              version.                       │
│ --out                     TEXT               Output directory (default:     │
│                                              cwd).                          │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit check

 Usage: pinman kit check [OPTIONS]

 Validate a project's kit membership (resolvable, requires, drift,
 collisions).
 Exit codes for scripting: 0 = every invariant holds, 1 = at least one
 violation (the report names which). A validation command that always exited 0
 could not be gated on.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Project to check (default:     │
│                                              active).                       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit create

 Usage: pinman kit create [OPTIONS] NAME

 Scaffold an empty kit skeleton NAME/ for an author to fill.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --out                     TEXT               Parent directory (default:     │
│                                              cwd).                          │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit import

 Usage: pinman kit import [OPTIONS] NAME

 Import an installed kit into the active project (schema merged; profiles;
 requires first).
 Idempotent: importing a kit the project already has is a no-op — for both the
 same version and a newer one. Pass --force to (re-)merge its schema,
 re-asserting the kit's authored values over your local edits; --force is also
 how you apply an upgrade.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit install

 Usage: pinman kit install [OPTIONS] SOURCE

 Install a kit from a .zip (or directory) onto this machine's hub store.
 Machine scope: makes the kit resolvable by name for every project. Pass
 --import to also import it into the active project in one step
 (community/beta content shows its disclaimer at the `import` step, where its
 code runs).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  SOURCE  PATH  [required]                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --import                                     Also import it into the active │
│                                              project.                       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit list

 Usage: pinman kit list [OPTIONS]

 List installed kits and the kits the active project has added.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman kit uninstall

 Usage: pinman kit uninstall [OPTIONS] NAME

 Uninstall a kit from this machine's hub store (inverse of install).
 Removes the kit's library copy. A project that already imported the kit keeps
 its merged schema (projects are disposable). A shipped master kit cannot be
 uninstalled.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log

 Usage: pinman log [OPTIONS] COMMAND [ARGS]...

 Application log commands.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Log ───────────────────────────────────────────────────────────────────────┐
│ show     Show the application log (optionally filtered by level).           │
│ clear    Clear the application log.                                         │
│ note     Record a note in the log (manual test-sequence marker).            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ list     List the log files, current and rotated, newest first.             │
│ rotate   Save the current log as a timestamped copy and start it fresh.     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log clear

 Usage: pinman log clear [OPTIONS]

 Clear the application log.
 Destructive: confirms in a terminal, refuses non-interactively without
 ``--force`` (exit 2).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --all                                        Also delete rotated copies of  │
│                                              the log.                       │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log list

 Usage: pinman log list [OPTIONS]

 List the log files, current and rotated, newest first.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log note

 Usage: pinman log note [OPTIONS] TEXT

 Record a note in the log (manual test-sequence marker).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  TEXT  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log rotate

 Usage: pinman log rotate [OPTIONS]

 Save the current log as a timestamped copy and start it fresh.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman log show

 Usage: pinman log show [OPTIONS]

 Show the application log (optionally filtered by level).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --level                   [debug|detail|info|warn  Show only lines at this  │
│                           ing|error|critical]      level (e.g. info | debug │
│                                                    | error).                │
│ --file                    TEXT                     A log named by `pinman   │
│                                                    log list` (default: the  │
│                                                    current pinman.log).     │
│ --lines                   INTEGER RANGE [x>=0]     Show the last N lines (0 │
│                                                    = the whole file).       │
│                                                    [default: 1000]          │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port

 Usage: pinman port [OPTIONS] COMMAND [ARGS]...

 Manage ports: topology, labeling, and device expectations.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Ports ─────────────────────────────────────────────────────────────────────┐
│ list     Show port topology with connected devices and labels.              │
│ label    Set or clear the user-assigned label on a port.                    │
│ expect   Pin a device as expected on a port, or clear the expectation.      │
│ reset    Clear all saved port data from the Computer.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ USB ───────────────────────────────────────────────────────────────────────┐
│ scan   Scan raw USB devices currently connected (training-wizard helper).   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port expect

 Usage: pinman port expect [OPTIONS] PORT_ID [DEVICE_NAME]

 Pin a device as expected on a port, or clear the expectation.
 PORT_ID is the ID, label or name `port list` shows. DEVICE_NAME is the device
 name or numeric ID. Omit to clear the pin.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PORT_ID      TEXT  [required]                                            │
│    DEVICE_NAME  TEXT                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port label

 Usage: pinman port label [OPTIONS] PORT_ID [LABEL]

 Set or clear the user-assigned label on a port.
 PORT_ID is the ID, label or name `port list` shows, or a USB location `port
 scan -v` shows that detect has not recorded yet. LABEL is the new name. Omit
 LABEL to clear it.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PORT_ID  TEXT  [required]                                                │
│    LABEL    TEXT                                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port list

 Usage: pinman port list [OPTIONS]

 Show port topology with connected devices and labels.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port reset

 Usage: pinman port reset [OPTIONS]

 Clear all saved port data from the Computer.
 Removes accumulated port history so the next 'detect' starts fresh.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman port scan

 Usage: pinman port scan [OPTIONS]

 Scan raw USB devices currently connected (training-wizard helper).
 Lists all USB classes: HID, serial/COM, audio, and others. A live hardware
 scan, independent of the device table.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman power

 Usage: pinman power [OPTIONS] COMMAND [ARGS]...

 Power control for this machine: shut down, reboot.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Power ─────────────────────────────────────────────────────────────────────┐
│ off               Shut down this machine.                                   │
│ reboot            Reboot this machine.                                      │
└─────────────────────────────────────────────────────────────────────────────┘

pinman power off

 Usage: pinman power off [OPTIONS]

 Shut down this machine.
 From source this only PRETENDS — see `PRETEND_REBOOT`. A frozen build is the
 one that really powers the machine off.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --allow-writes            Write to the machine even though machine_readonly │
│                           is enabled.                                       │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman power reboot

 Usage: pinman power reboot [OPTIONS]

 Reboot this machine.
 From source this only PRETENDS — see `PRETEND_REBOOT`.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --allow-writes            Write to the machine even though machine_readonly │
│                           is enabled.                                       │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile

 Usage: pinman profile [OPTIONS] COMMAND [ARGS]...

 Manage reusable desired-state recipes.
 Profiles express intent; captures supply authoring evidence and live state
 supplies comparison context. Authoring tools live under `pinman profile
 authoring`; per-profile target management under `pinman profile target`.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Apply ─────────────────────────────────────────────────────────────────────┐
│ preview  Preview what applying a profile would change.                      │
│ apply    Apply a profile's target values to live configuration.             │
│ status   Check whether a profile's targets match live values.               │
│ refresh  Refresh capture values for a profile's target locations.           │
│ undo     Undo the most recent apply for a profile (restore previous         │
│          values).                                                           │
│ revert   Revert disruptive (display) changes from an apply, keeping other   │
│          changes.                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Manage ────────────────────────────────────────────────────────────────────┐
│ list     List all profiles from the registry.                               │
│ show     Show profile details (metadata, inputs, targets).                  │
│ rename   Rename a profile (.py file + registry + history + journal          │
│          cascade).                                                          │
│ edit     Edit a profile's `.py` script.                                     │
│ delete   Delete a profile (.py file + registry entry).                      │
│ history  Show apply history for a profile (or all profiles).                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Author ────────────────────────────────────────────────────────────────────┐
│ compose  Generate one profile whose select choices use source-profile       │
│          target values.                                                     │
│ collect  Generate a literal profile from reviewed selected items.           │
│ relink   Reattach history after an out-of-band profile rename.              │
│ sync     Reconcile the profile registry with the on-disk profiles           │
│          directory.                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Sub-groups ────────────────────────────────────────────────────────────────┐
│ authoring  Author profile scripts: scaffold · inspect compiled intent ·     │
│            lint.                                                            │
│ target     Manage a profile's targets: list · add · remove.                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ allow-full-python  Trust one exact Profile Script version with full Python. │
│ disable            Remove a profile from normal top-level use.              │
│ edit-history       List, inspect, restore, or clean saved profile source    │
│                    versions.                                                │
│ enable             Make a profile available as a top-level action.          │
│ pin                Add a profile to the Dashboard.                          │
│ restrict           Return a Profile Script to Restricted mode.              │
│ run                Run a sequenced profile — its steps, holds and commands, │
│                    in order.                                                │
│ unpin              Remove a profile from the Dashboard.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile allow-full-python

 Usage: pinman profile allow-full-python [OPTIONS] NAME_OR_PATH

 Trust one exact Profile Script version with full Python.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME_OR_PATH  TEXT  [required]                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile apply

 Usage: pinman profile apply [OPTIONS] NAME

 Apply a profile's target values to live configuration.
 `--dry-run` renders a real preview (no changes). Disruptive changes (e.g.
 display settings) prompt for confirmation; `--force` skips the prompt, and a
 non-interactive apply of a disruptive profile refuses without `--force`.
 When `machine_readonly` is enabled the apply is previewed instead — pass
 `--allow-writes` to authorize this one invocation to write anyway.
 With `require_savepoint` on, a file no Savepoint holds as it is now is
 refused: `--take-savepoint` takes one first, `--overwrite-unsaved` changes it
 anyway.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                     TEXT               Interface value in key=value │
│                                                format; repeat for multiple  │
│                                                inputs. Values are coerced   │
│                                                and validated by the profile │
│                                                definition.                  │
│ --no-check                                     Skip pre-check (allow        │
│                                                partial apply on errors).    │
│ --no-refresh                                   Skip refresh (use cached     │
│                                                values).                     │
│ --dry-run                                      Preview what would change    │
│                                                without applying it.         │
│ --force              -f                        Skip the confirmation prompt │
│                                                (and authorize the op when   │
│                                                non-interactive).            │
│ --allow-writes                                 Write to the machine even    │
│                                                though machine_readonly is   │
│                                                enabled.                     │
│ --take-savepoint                               Take a Savepoint first, so   │
│                                                what this changes can be put │
│                                                back.                        │
│ --overwrite-unsaved                            Change files even when no    │
│                                                Savepoint holds them as they │
│                                                are now.                     │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile authoring

 Usage: pinman profile authoring [OPTIONS] COMMAND [ARGS]...

 Author profile scripts: scaffold · inspect compiled intent · lint.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Authoring ─────────────────────────────────────────────────────────────────┐
│ scaffold  Generate a profile script scaffold.                               │
│ check     Inspect a script's declared Interface and compiled intent without │
│           applying.                                                         │
│ lint      Validate a profile script's declarations and writable target      │
│           structure.                                                        │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile authoring check

 Usage: pinman profile authoring check [OPTIONS] PATH

 Inspect a script's declared Interface and compiled intent without applying.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PATH  PATH  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                   TEXT               Interface value in key=value   │
│                                              format; repeat for multiple    │
│                                              inputs. Values are coerced and │
│                                              validated by the profile       │
│                                              definition.                    │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile authoring lint

 Usage: pinman profile authoring lint [OPTIONS] PATH

 Validate a profile script's declarations and writable target structure.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PATH  PATH  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                   TEXT               Interface value in key=value   │
│                                              format; repeat for multiple    │
│                                              inputs. Values are coerced and │
│                                              validated by the profile       │
│                                              definition.                    │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile authoring scaffold

 Usage: pinman profile authoring scaffold [OPTIONS] NAME

 Generate a profile script scaffold.
 Writes to `<profiles-dir>/<slug>.py` by default; `--file PATH` overrides the
 destination. `--force` overwrites an existing file without prompting.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --file                    FILE  Write the payload to this file as UTF-8     │
│                                 (default: stdout).                          │
│ --force            -f           Skip the confirmation prompt (and authorize │
│                                 the op when non-interactive).               │
│ --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress    │
│                                 logs (applies to the whole run; default     │
│                                 quiet — PINMAN_VERBOSE env var sets the     │
│                                 default).                                   │
│ --help             -h,-?        Show this message and exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile collect

 Usage: pinman profile collect [OPTIONS] NAME

 Generate a literal profile from reviewed selected items.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --items                   TEXT               Reviewed JSON target        │
│                                                 mappings; literal sets      │
│                                                 require location and value. │
│                                                 [required]                  │
│    --zone                    TEXT               Zone tag (can repeat).      │
│    --description             TEXT               Profile description.        │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile compose

 Usage: pinman profile compose [OPTIONS] NAME

 Generate one profile whose select choices use source-profile target values.
 This creates choices, not an assembly. Use p.include() or the Assembly tab
 when the child profiles should remain ordered components.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --from                    TEXT               Source profile .py file     │
│                                                 used as one choice; repeat  │
│                                                 in desired choice order.    │
│                                                 [required]                  │
│    --zone                    TEXT               Zone tag (can repeat).      │
│    --description             TEXT               Profile description.        │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile delete

 Usage: pinman profile delete [OPTIONS] NAME

 Delete a profile (.py file + registry entry).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile disable

 Usage: pinman profile disable [OPTIONS] NAME

 Remove a profile from normal top-level use.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile edit

 Usage: pinman profile edit [OPTIONS] NAME

 Edit a profile's `.py` script.
 With no options, opens the script in your `$EDITOR`. With `--from-file`,
 replaces the source from a file (non-interactive). The previous version is
 snapshotted to `_history/` only when the source actually changes, and the
 result is re-validated.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --from-file               FILE  Replace the profile's source with this      │
│                                 file's contents (non-interactive).          │
│ --verbose/--quiet  -v/-q        Echo/hide detailed output incl. progress    │
│                                 logs (applies to the whole run; default     │
│                                 quiet — PINMAN_VERBOSE env var sets the     │
│                                 default).                                   │
│ --help             -h,-?        Show this message and exit.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile edit-history

 Usage: pinman profile edit-history [OPTIONS] NAME

 List, inspect, restore, or clean saved profile source versions.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --limit                   INTEGER RANGE [x>=0]  Max versions to list.       │
│ --show                    VERSION               Show one saved source       │
│                                                 version.                    │
│ --restore                 VERSION               Restore one saved source    │
│                                                 version.                    │
│ --undo                                          Undo the last saved source  │
│                                                 edit.                       │
│ --clean                                         Apply edit-history          │
│                                                 retention now.              │
│ --keep                    INTEGER RANGE [x>=0]  With --clean: keep at most  │
│                                                 N newest versions (default: │
│                                                 50).                        │
│ --older-than              INTEGER RANGE [x>=0]  With --clean: remove        │
│                                                 versions older than N days  │
│                                                 (default: 180).             │
│ --force            -f                           Skip the confirmation       │
│                                                 prompt (and authorize the   │
│                                                 op when non-interactive).   │
│ --output           -o     [human|json|yaml]     Output format (human | json │
│                                                 | yaml). [default: human]   │
│ --verbose/--quiet  -v/-q                        Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│ --help             -h,-?                        Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile enable

 Usage: pinman profile enable [OPTIONS] NAME

 Make a profile available as a top-level action.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile history

 Usage: pinman profile history [OPTIONS] [NAME]

 Show apply history for a profile (or all profiles).
 With `--clean --older-than N`, delete apply-history records older than N days
 instead of listing.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --limit                   INTEGER            Max records to show.           │
│ --clean                                      Delete old history records     │
│                                              (requires --older-than).       │
│ --older-than              INTEGER            With --clean: delete records   │
│                                              older than N days.             │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile list

 Usage: pinman profile list [OPTIONS]

 List all profiles from the registry.
 By default reconciles the registry with the on-disk profiles directory before
 listing. Pass `--no-sync` to read the DB as-is.
 Live: `=` in sync, `~` drift, `?` unknown, `x` missing, `-` empty; blank
 means a profile with required inputs and no apply history (no target values
 to check against yet).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --zone                    TEXT               Filter by zone (can repeat).   │
│ --no-sync                                    Skip the implicit registry     │
│                                              sync (read DB as-is).          │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile pin

 Usage: pinman profile pin [OPTIONS] NAME

 Add a profile to the Dashboard.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile preview

 Usage: pinman profile preview [OPTIONS] NAME

 Preview what applying a profile would change.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                   TEXT               Interface value in key=value   │
│                                              format; repeat for multiple    │
│                                              inputs. Values are coerced and │
│                                              validated by the profile       │
│                                              definition.                    │
│ --no-refresh                                 Skip refresh (use cached       │
│                                              values).                       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile refresh

 Usage: pinman profile refresh [OPTIONS] [NAME]

 Refresh capture values for a profile's target locations.
 Pass `--all` to refresh every profile (deduplicated) and report their status.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                   TEXT               Interface value in key=value   │
│                                              format; repeat for multiple    │
│                                              inputs. Values are coerced and │
│                                              validated by the profile       │
│                                              definition.                    │
│ --all                                        Refresh all profiles           │
│                                              (deduplicated) and show        │
│                                              status.                        │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile rename

 Usage: pinman profile rename [OPTIONS] OLD_NAME NEW_NAME

 Rename a profile (.py file + registry + history + journal cascade).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  OLD_NAME  TEXT  [required]                                               │
│ *  NEW_NAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile restrict

 Usage: pinman profile restrict [OPTIONS] NAME_OR_PATH

 Return a Profile Script to Restricted mode.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME_OR_PATH  TEXT  [required]                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile revert

 Usage: pinman profile revert [OPTIONS] NAME

 Revert disruptive (display) changes from an apply, keeping other changes.
 Unlike `undo` (which restores every setting), `revert` rolls back only the
 disruptive WinRT display changes from a history record — the CLI counterpart
 of the UI's post-apply "Revert" countdown.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --record-id               INTEGER            Specific history record ID to  │
│                                              revert.                        │
│ --allow-writes                               Write to the machine even      │
│                                              though machine_readonly is     │
│                                              enabled.                       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile run

 Usage: pinman profile run [OPTIONS] NAME

 Run a sequenced profile — its steps, holds and commands, in order.
 A run is cancellable: Ctrl+C stops it between steps or during a hold, and the
 process exits 130. Use ``pinman profile apply`` for a profile that carries
 desired state instead of steps.
 ``--allow-writes`` is the same per-invocation read-only override apply takes;
 without it a stock install (``machine_readonly`` on) refuses every run.
 ``--take-savepoint`` and ``--overwrite-unsaved`` answer
 ``require_savepoint``, as on apply.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force              -f                        Skip the confirmation prompt │
│                                                (and authorize the op when   │
│                                                non-interactive).            │
│ --allow-writes                                 Write to the machine even    │
│                                                though machine_readonly is   │
│                                                enabled.                     │
│ --take-savepoint                               Take a Savepoint first, so   │
│                                                what this changes can be put │
│                                                back.                        │
│ --overwrite-unsaved                            Change files even when no    │
│                                                Savepoint holds them as they │
│                                                are now.                     │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile show

 Usage: pinman profile show [OPTIONS] NAME

 Show profile details (metadata, inputs, targets).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile status

 Usage: pinman profile status [OPTIONS] NAME

 Check whether a profile's targets match live values.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --input                   TEXT               Interface value in key=value   │
│                                              format; repeat for multiple    │
│                                              inputs. Values are coerced and │
│                                              validated by the profile       │
│                                              definition.                    │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile sync

 Usage: pinman profile sync [OPTIONS]

 Reconcile the profile registry with the on-disk profiles directory.
 Adds new files, restores rows whose files reappeared, refreshes metadata for
 modified files, and marks rows whose files were deleted as `state='missing'`.
 With `--remove-missing`, missing rows are deleted with their apply history.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --remove-missing                             Delete registry rows (and      │
│                                              their apply history) for files │
│                                              no longer on disk.             │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile target

 Usage: pinman profile target [OPTIONS] COMMAND [ARGS]...

 Manage a profile's targets: list · add · remove.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Targets ───────────────────────────────────────────────────────────────────┐
│ list    List a profile's targets (property + file targets).                 │
│ add     Add a target (by LOCATION, e.g. fs:/path/file.ini#Sec/Key) to a     │
│         profile's script.                                                   │
│ remove  Remove a target (by LOCATION) from a profile's script.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile target add

 Usage: pinman profile target add [OPTIONS] NAME LOCATION

 Add a target (by LOCATION, e.g. fs:/path/file.ini#Sec/Key) to a profile's
 script.
 The item type is inferred from the location's schema at apply time, so it is
 not specified here.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME      TEXT  [required]                                               │
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --value                   TEXT               Target value to set.        │
│                                                 [required]                  │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile target list

 Usage: pinman profile target list [OPTIONS] NAME

 List a profile's targets (property + file targets).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile target remove

 Usage: pinman profile target remove [OPTIONS] NAME LOCATION

 Remove a target (by LOCATION) from a profile's script.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME      TEXT  [required]                                               │
│ *  LOCATION  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile undo

 Usage: pinman profile undo [OPTIONS] NAME

 Undo the most recent apply for a profile (restore previous values).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --record-id                 INTEGER            Specific history record ID   │
│                                                to undo.                     │
│ --allow-writes                                 Write to the machine even    │
│                                                though machine_readonly is   │
│                                                enabled.                     │
│ --take-savepoint                               Take a Savepoint first, so   │
│                                                what this changes can be put │
│                                                back.                        │
│ --overwrite-unsaved                            Change files even when no    │
│                                                Savepoint holds them as they │
│                                                are now.                     │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman profile unpin

 Usage: pinman profile unpin [OPTIONS] NAME

 Remove a profile from the Dashboard.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project

 Usage: pinman project [OPTIONS] COMMAND [ARGS]...

 Manage pinman projects (independent data homes on this machine).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Projects ──────────────────────────────────────────────────────────────────┐
│ create   Create a pinman project (create DB, import + adopt kits, configure │
│          backups_root).                                                     │
│ use      Switch the active project.                                         │
│ list     List projects on this machine (active is marked; api-running       │
│          noted).                                                            │
│ current  Show the current (active) project and its resolved home.           │
│ rename   Rename a project (label only; the home directory path is           │
│          unchanged).                                                        │
│ delete   Delete a project: delete its home directory and its catalog entry. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project create

 Usage: pinman project create [OPTIONS] [NAME]

 Create a pinman project (create DB, import + adopt kits, configure
 backups_root).
 Idempotent: an existing database is migrated to head rather than recreated.
 Registers the project in the env's catalog and makes it active, recording its
 adopted kits. Without --kit, the 'blank' kit is adopted (realm-root
 scaffolding only — a browsable, nothing-tracked project). The platform
 baseline (OS software catalog + reference data) is always present without
 adoption. With --from-project, the new project imports a schema cloned from a
 live one and adopts no kits.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  TEXT                                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --home                    DIRECTORY          Home directory for a new       │
│                                              project (prod only). Defaults  │
│                                              to <hub>/projects/<name>.      │
│ --backups                 DIRECTORY          Path to the backups root       │
│                                              directory. Defaults to a       │
│                                              per-project path when          │
│                                              prompted.                      │
│ --backups-default                            Use the default in-home        │
│                                              backups root without prompting │
│                                              (unattended installs). Ignored │
│                                              if --backups is given.         │
│ --kit                     TEXT               Kit name whose schema/ to      │
│                                              import + adopt; repeatable, in │
│                                              order. Without it, the 'blank' │
│                                              kit (realm-root scaffolding,   │
│                                              nothing tracked) is adopted.   │
│ --from-project            TEXT               Clone a live project's schema  │
│                                              into the new project           │
│                                              (experimentation; the source   │
│                                              is untouched). Schema-only —   │
│                                              no fixtures, config, or        │
│                                              captures.                      │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project current

 Usage: pinman project current [OPTIONS]

 Show the current (active) project and its resolved home.
 Prints "(none)" when no project is selected, and marks one that is selected
 but not created yet.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project delete

 Usage: pinman project delete [OPTIONS] NAME

 Delete a project: delete its home directory and its catalog entry.
 Destructive: the home (db, config, profiles, in-home backups) is deleted.
 Backups relocated outside the home are untouched. Deleting the *active*
 project offers to stop the tray and its services first (they hold the home
 open), then the alphabetically-first remaining project becomes active and the
 tray restarts onto it. If it was the only project, no project is active
 afterwards and the tray is left stopped (create a new one to start again).
 With --force, a NAME the catalog doesn't know deletes any leftover home
 directory of that name — logs and all — or does nothing if there is none.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project list

 Usage: pinman project list [OPTIONS]

 List projects on this machine (active is marked; api-running noted).
 With --verbose, also lists home directories that no catalog entry claims.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project rename

 Usage: pinman project rename [OPTIONS] OLD NEW

 Rename a project (label only; the home directory path is unchanged).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  OLD  TEXT  [required]                                                    │
│ *  NEW  TEXT  [required]                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman project use

 Usage: pinman project use [OPTIONS] NAME

 Switch the active project.
 The switch only takes effect when the services next start, so while the
 service is running this offers to stop it, switch, and restart it (so it
 comes back on the newly-selected project). Use --force to skip the prompt.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema

 Usage: pinman schema [OPTIONS] COMMAND [ARGS]...

 Schema related commands.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inspect ───────────────────────────────────────────────────────────────────┐
│ show       Show schema information.                                         │
│ export     Export schema in clean, DRY format (smart export).               │
│ dump       Dump schema tree structure (raw database format).                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Manage ────────────────────────────────────────────────────────────────────┐
│ import    Import schema definitions from a file, directory, or kit.         │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ item        Inspect and author individual schema definitions.               │
│ validate    Validate schema YAML independently of the active project.       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema dump

 Usage: pinman schema dump [OPTIONS]

 Dump schema tree structure (raw database format).
 Default (-o human) renders colorized JSON to the terminal; -o json / -o yaml
 emit the raw payload to stdout. Use --file to write to disk.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --file                    FILE               Write the payload to this file │
│                                              as UTF-8 (default: stdout).    │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema export

 Usage: pinman schema export [OPTIONS]

 Export schema in clean, DRY format (smart export).
 Default (-o human) renders colorized YAML to the terminal; -o yaml / -o json
 emit the raw payload to stdout (pipe-friendly). Use --file to write to disk.
 Examples:
   Export everything for specific software (entry + associated items):
     pinman schema export --software dof -o yaml --file dof.yaml
   Export only the software: section, filtered to nvidia entries:
     pinman schema export --section software --software nvidia -o yaml --file
 core_nvidia.yaml
   Pipe JSON to another tool:
     pinman schema export --by-software -o json | jq '.items'
   Export one item's subtree for a support repair (edit, then re-apply
 scoped):
     pinman schema export --item 'winreg:/HKEY_CURRENT_USER/Software/MyApp' \
       -o yaml --file myapp.yaml
     pinman schema import myapp.yaml --replace \
       --item 'winreg:/HKEY_CURRENT_USER/Software/MyApp'

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --file                    FILE               Write the payload to this file │
│                                              as UTF-8 (default: stdout).    │
│ --by-software                                Organize items by primary      │
│                                              software_ref at top level      │
│                                              using virtual wrappers         │
│ --section                 [software|items]   Export only this section       │
│                                              (software: entries or items    │
│                                              tree)                          │
│ --no-section              [software|items]   Exclude this section from      │
│                                              export                         │
│ --software                PATTERN            Include only content matching  │
│                                              this software ID (repeatable;  │
│                                              "dof" means "dof:*")           │
│ --no-software             PATTERN            Exclude content matching this  │
│                                              software ID (repeatable; "dof" │
│                                              means "dof:*")                 │
│ --item                    LOCATION           Export only this item's        │
│                                              subtree as an items-only       │
│                                              fragment (re-apply with        │
│                                              'schema import --replace       │
│                                              --item LOCATION')              │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema import

 Usage: pinman schema import [OPTIONS] FILE_PATH_OR_PACKAGE

 Import schema definitions from a file, directory, or kit.
 FILE_PATH_OR_PACKAGE may be a YAML file, a directory (imports all *.yaml
 files found in it), or a bare kit name resolved to the kit's schema/
 directory across the kit roots. Catalog-only files (software: without items:)
 upsert SoftwareEntry records.
 Default is an idempotent create-or-merge: create the schema when the project
 has none, else additively merge (union tags/software_refs, per-key vars/props
 — never deletes). Uniform across file, directory, and kit inputs. Pass
 --replace for a destructive sync that removes items not in the YAML.
 With --dry-run, the exact operation runs against an isolated project clone
 and reports semantic definition/declaration changes, linked rows and Capture
 requirements. Use '-' as the file to plan YAML from stdin. Directory and kit
 imports do not support --dry-run.
 (kit import is the guarded normal path for adopting kit content; plain schema
 import is the lower-level tool.)

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FILE_PATH  PATH  [required]                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --name                          TEXT               Override the schema      │
│                                                    selector in the file     │
│ --replace                                          Re-import an             │
│                                                    edited/updated YAML:     │
│                                                    destructive sync         │
│                                                    (preserves IDs, syncs    │
│                                                    tags, REMOVES items not  │
│                                                    in the YAML). Without    │
│                                                    it, import is an         │
│                                                    idempotent               │
│                                                    create-or-merge (creates │
│                                                    the schema, or merges    │
│                                                    additively — never       │
│                                                    deletes).                │
│ --no-orphan-check                                  Skip check for orphaned  │
│                                                    tags (tags on items not  │
│                                                    in new zone_defs)        │
│ --allow-itemtype-change                            Allow itemtype changes   │
│                                                    on existing items during │
│                                                    --replace                │
│ --item                          LOCATION           Confine --replace to the │
│                                                    subtree at this item     │
│                                                    location (bounded        │
│                                                    repair; nothing outside  │
│                                                    is added, updated, or    │
│                                                    deleted). Pairs with     │
│                                                    'schema export --item'.  │
│ --dry-run                                          Preview what would       │
│                                                    change without applying  │
│                                                    it.                      │
│ --strict-software-refs                             Fail if any              │
│                                                    software_refs IDs are    │
│                                                    undefined in the catalog │
│ --output                 -o     [human|json|yaml]  Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet        -v/-q                     Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help                   -h,-?                     Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item

 Usage: pinman schema item [OPTIONS] COMMAND [ARGS]...

 Inspect and author individual schema definitions.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ add     Create one schema definition under PARENT.                          │
│ edit    Patch guide fields, or replace a complete definition from a file.   │
│ for     Create and maintain structural iteration templates.                 │
│ list    List schema definitions in hierarchy order.                         │
│ move    Reorder one definition relative to a sibling without reparenting    │
│         it.                                                                 │
│ remove  Remove one leaf definition and orphan its linked rows.              │
│ show    Show one schema definition by canonical location or #ID.            │
│ var     List and edit definition variables without a YAML file.             │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item add

 Usage: pinman schema item add [OPTIONS] PARENT

 Create one schema definition under PARENT.
 PARENT accepts a canonical location or #ID. Common metadata can be supplied
 directly; --definition-file adds advanced guide-shaped fields atomically.
 --row-var creates a supported row template with the definition. Structural
 for-blocks use the dedicated schema item for workflow.
 Examples:
   pinman schema item add '#2' --selector C/App --itemtype directory --zone
 Production
   pinman schema item add 'fs:/C/App' --selector hosts.csv --itemtype csv_file
 --row-var HOST
   pinman schema item add '#17' --selector controls --itemtype rest_service
 --definition-file service.json

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PARENT  TEXT  [required]                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --selector                TEXT               Name or relative path under │
│                                                 PARENT. [required]          │
│ *  --itemtype                TEXT               Schema item type to create. │
│                                                 [required]                  │
│    --definition-file         FILE               Optional YAML/JSON          │
│                                                 fragment; use '-' for       │
│                                                 stdin. Explicit flags       │
│                                                 override it.                │
│    --label                   TEXT               Human-readable label.       │
│    --description             TEXT               Longer definition           │
│                                                 description.                │
│    --zone                    TEXT               Assign a defined Zone;      │
│                                                 repeatable.                 │
│    --software                TEXT               Assign a Software           │
│                                                 declaration ID; repeatable. │
│    --const                   NAME=VALUE         Set a definition constant;  │
│                                                 repeatable.                 │
│    --row-var                 NAME               Also create the adapter's   │
│                                                 row-placeholder child as    │
│                                                 {{NAME}}.                   │
│    --dry-run                                    Preview what would change   │
│                                                 without applying it.        │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item edit

 Usage: pinman schema item edit [OPTIONS] ITEM

 Patch guide fields, or replace a complete definition from a file.
 Without --definition-file, omitted fields are preserved. A Definition file
 remains a complete replacement: its omissions clear content, then explicit
 flags override it. All changes are adapter-validated and atomic.
 Repeat --set/--set-json to validate jointly-required fields atomically.
 Examples:
   pinman schema item edit 'fs:/C/App' --set follow_links=false
   pinman schema item edit '#8' --set-json primary_key='["system","name"]'
   pinman schema item edit '#18' --set path_prefix=/api/controls --set
 service=api
   pinman schema item edit '#19' --set-json
 read='{"path":"/api/controls","pointer":"volume"}'

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --definition-file         FILE               Optional full YAML/JSON        │
│                                              replacement; use '-' for       │
│                                              stdin. Flags override it.      │
│ --set                     FIELD=VALUE        Set a guide field using a      │
│                                              typed scalar; adapter fields   │
│                                              need no schema_props prefix.   │
│ --set-json                FIELD=JSON         Set a list, mapping, or        │
│                                              explicitly JSON-typed guide    │
│                                              field; repeatable.             │
│ --unset                   FIELD              Remove an explicit guide field │
│                                              so it clears or returns to     │
│                                              inheritance; repeatable.       │
│ --const                   NAME=VALUE         Set or replace one definition  │
│                                              constant; repeatable.          │
│ --remove-const            NAME               Remove one definition          │
│                                              constant; repeatable.          │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item for

 Usage: pinman schema item for [OPTIONS] COMMAND [ARGS]...

 Create and maintain structural iteration templates.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ add      Create a for block and its required template child atomically.     │
│ edit     Edit a for binding without replacing its template subtree.         │
│ remove   Remove a for block and its complete template subtree.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item for add

 Usage: pinman schema item for add [OPTIONS] PARENT

 Create a for block and its required template child atomically.
 PARENT accepts a canonical location or #ID. Nest another block by using an
 existing template child as PARENT. --before controls first-match priority.
 Example:
   pinman schema item for add 'fs:/C/App/codecs' --var CODEC --pattern
 '*.codec' --itemtype file

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PARENT  TEXT  [required]                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ *  --var                     TEXT               Iteration variable name.    │
│                                                 [required]                  │
│ *  --pattern                 TEXT               Adapter match pattern for   │
│                                                 the variable. [required]    │
│    --selector                TEMPLATE           Template selector; defaults │
│                                                 to '{{VAR}}'.               │
│ *  --itemtype                TEXT               Item type for the template  │
│                                                 definition. [required]      │
│    --definition-file         FILE               Optional YAML/JSON fragment │
│                                                 for the template; use '-'   │
│                                                 for stdin.                  │
│    --before                  SIBLING            Insert the block before     │
│                                                 this sibling location or    │
│                                                 #ID.                        │
│    --dry-run                                    Preview what would change   │
│                                                 without applying it.        │
│    --output           -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│    --verbose/--quiet  -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│    --help             -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item for edit

 Usage: pinman schema item for edit [OPTIONS] FOR_ITEM

 Edit a for binding without replacing its template subtree.
 Renaming a variable updates {{VAR}} references and descendant template
 locations while preserving definition IDs.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  FOR_ITEM  [required]                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --var                     TEXT               Rename the iteration variable. │
│ --pattern                 TEXT               Replace the adapter match      │
│                                              pattern.                       │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item for remove

 Usage: pinman schema item for remove [OPTIONS] FOR_ITEM

 Remove a for block and its complete template subtree.
 A real removal requires interactive confirmation or --force. Use --dry-run to
 inspect every definition and linked row that would be removed.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  FOR_ITEM  [required]                                            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item list

 Usage: pinman schema item list [OPTIONS]

 List schema definitions in hierarchy order.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --parent                  ITEM               List only the immediate        │
│                                              children of this canonical     │
│                                              location or #ID.               │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item move

 Usage: pinman schema item move [OPTIONS] ITEM

 Reorder one definition relative to a sibling without reparenting it.
 Specify exactly one of --before or --after. The explicit order persists and
 controls first-match precedence where sibling definitions overlap.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --before                  SIBLING            Place ITEM immediately before  │
│                                              this sibling location or #ID.  │
│ --after                   SIBLING            Place ITEM immediately after   │
│                                              this sibling location or #ID.  │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item remove

 Usage: pinman schema item remove [OPTIONS] ITEM

 Remove one leaf definition and orphan its linked rows.
 Definitions with children are refused; remove children first. A real removal
 requires interactive confirmation or --force. Use --dry-run to inspect the
 exact impact without authorization or mutation.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item show

 Usage: pinman schema item show [OPTIONS] ITEM

 Show one schema definition by canonical location or #ID.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --definition                                 Emit only the guide-shaped     │
│                                              editable fragment (no          │
│                                              identity, hierarchy, or        │
│                                              children).                     │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item var

 Usage: pinman schema item var [OPTIONS] COMMAND [ARGS]...

 List and edit definition variables without a YAML file.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ list         List editable variables owned by ITEM.                         │
│ remove       Remove one variable owned by ITEM.                             │
│ set          Set one string variable on ITEM.                               │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item var list

 Usage: pinman schema item var list [OPTIONS] ITEM

 List editable variables owned by ITEM.
 Inherited and Pinman-managed variables are not included. Global variables are
 available only when ITEM is the schema root.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --scope                   [const|global]     Show only local constants or   │
│                                              root globals; omitted shows    │
│                                              every editable scope.          │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item var remove

 Usage: pinman schema item var remove [OPTIONS] ITEM NAME

 Remove one variable owned by ITEM.
 Removing an absent variable is a successful no-op. Use --dry-run to inspect
 the normalized definition result without changing the project.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
│ *  NAME     TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --scope                   [const|global]     Remove a definition constant   │
│                                              or a schema-root global.       │
│                                              [default: const]               │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema item var set

 Usage: pinman schema item var set [OPTIONS] ITEM NAME VALUE

 Set one string variable on ITEM.
 Constants are local to ITEM. Global variables require ITEM to be the schema
 root; Pinman-managed platform globals are read-only.
 Examples:
   pinman schema item var set 'fs:/C/App' APP_ROOT fs:/C/App
   pinman schema item var set '#1' SHARED_ROOT fs:/C/Shared --scope global

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  ADDRESS  ITEM  [required]                                                │
│ *  NAME     TEXT  [required]                                                │
│ *  VALUE    TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --scope                   [const|global]     Write a definition constant or │
│                                              a schema-root global.          │
│                                              [default: const]               │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema show

 Usage: pinman schema show [OPTIONS]

 Show schema information.
 Without flags, shows a brief summary. Use ``--device-roles`` to list hardware
 role definitions.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --device-roles                               Show device role definitions   │
│                                              for this schema                │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman schema validate

 Usage: pinman schema validate [OPTIONS] FILE

 Validate schema YAML independently of the active project.
 Checks syntax and the real importer, adapter, declaration, tag and Software
 reference rules in a disposable database. Reports normalized issues; it does
 not compare against or change the active schema. Use '-' as FILE to read YAML
 from stdin.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FILE_PATH  FILE  [required]                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service

 Usage: pinman service [OPTIONS] COMMAND [ARGS]...

 Manage Pinman's services and the tray that supervises them.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inventory ─────────────────────────────────────────────────────────────────┐
│ list     List Pinman's services and whether each is running.                │
│ show     Show details for one Pinman service (NAME is a service slug).      │
│ status   Is Pinman running? Reports the tray plus every service under it.   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Lifecycle ─────────────────────────────────────────────────────────────────┐
│ start      Start Pinman, or one service by NAME.                            │
│ stop       Stop Pinman, or one service by NAME (disruptive).                │
│ restart    Restart Pinman, or one service by NAME (disruptive).             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Operations ────────────────────────────────────────────────────────────────┐
│ logs       Show recent log output for a Pinman service (NAME is a service   │
│            slug).                                                           │
│ autostart  Start Pinman (tray + services) automatically at Windows login.   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service autostart

 Usage: pinman service autostart [OPTIONS] [[on|off]]

 Start Pinman (tray + services) automatically at Windows login.
 With no argument, shows the current autostart status. ``on`` writes the HKCU
 Run entry for this installation; ``off`` removes it. The entry is
 intentionally visible in winreg captures ("User Startup Programs").

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ STATE  [[on|off]]                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service list

 Usage: pinman service list [OPTIONS]

 List Pinman's services and whether each is running.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service logs

 Usage: pinman service logs [OPTIONS] {api|overlay|audio|inputs}

 Show recent log output for a Pinman service (NAME is a service slug).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  {api|overlay|audio|inputs}  [required]                             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --lines                   INTEGER            Number of lines to show.       │
│                                              [default: 100]                 │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service restart

 Usage: pinman service restart [OPTIONS] [[api|overlay|audio|inputs]]

 Restart Pinman, or one service by NAME (disruptive).
 With no NAME this takes the whole tree down and brings it back — the
 operator's one-shot recovery. With a NAME it asks the running tray to restart
 that one service.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  [[api|overlay|audio|inputs]]                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service show

 Usage: pinman service show [OPTIONS] {api|overlay|audio|inputs|scheduler}

 Show details for one Pinman service (NAME is a service slug).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  {api|overlay|audio|inputs|schedu  [required]                       │
│          ler}                                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service start

 Usage: pinman service start [OPTIONS] [[api|overlay|audio|inputs]]

 Start Pinman, or one service by NAME.
 With no NAME this starts the tray, which brings up every service it
 supervises. With a NAME it asks the *running* tray to start that one service.
 ``--welcome/--no-welcome`` and ``--open-ui/--no-open-ui`` override what the
 tray would decide on its own — useful for an unattended start that should put
 nothing on screen (``--no-welcome``), or for a start that should land the
 user on the dashboard (``--open-ui``). Omitted, the tray's own defaults
 apply: welcome window shown and auto-dismissing, no browser.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  [[api|overlay|audio|inputs]]                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --welcome/--no-welcome                            Show or suppress the      │
│                                                   welcome/QR window         │
│                                                   (default: show,           │
│                                                   auto-dismissing).         │
│ --open-ui/--no-open-ui                            Open the dashboard in a   │
│                                                   browser once the API      │
│                                                   answers (default: don't). │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service status

 Usage: pinman service status [OPTIONS]

 Is Pinman running? Reports the tray plus every service under it.
 The runtime answer, where `service list` is the inventory: the supervisor's
 own state first (nothing below it runs without it), then a line per service
 that isn't up.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman service stop

 Usage: pinman service stop [OPTIONS] [[api|overlay|audio|inputs]]

 Stop Pinman, or one service by NAME (disruptive).
 With no NAME this stops the tray and every service under it. With a NAME the
 stop routes through the tray supervisor when it's running (the service stays
 down until started again); with no tray, a standalone service (dev) is
 stopped via its own shutdown endpoint, and the in-process Scheduler can't be.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME  [[api|overlay|audio|inputs]]                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman setup

 Usage: pinman setup [OPTIONS]

 Guided first-run: create your first project (from a tutorial, kits, or
 blank).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --no-start                Don't offer to start Pinman at the end (the       │
│                           installer starts it itself).                      │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software

 Usage: pinman software [OPTIONS] COMMAND [ARGS]...

 Manage Software catalog definitions, detection, and inventory.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Catalog ───────────────────────────────────────────────────────────────────┐
│ list     List detected software from the catalog.                           │
│ show     Show detail for one catalog entry by name, label, or numeric ID.   │
│ detect   Detect software availability on the system.                        │
│ launch   Launch an external software/tool by name, label, or numeric ID.    │
│ reset    Clear detected machine state without deleting catalog definitions. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ create  Create a Software catalog definition without detecting machine      │
│         availability.                                                       │
│ delete  Delete a catalog definition and report/clean active references.     │
│ edit    Edit authored catalog fields while preserving detected machine      │
│         state.                                                              │
│ export  Export one catalog definition in reusable `software:` schema shape. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software create

 Usage: pinman software create [OPTIONS] NAME

 Create a Software catalog definition without detecting machine availability.
 Supply `--label` and `--class` for common entries, or a Definition file for
 the complete schema-format entry.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --label                   TEXT               Human-readable catalog label.  │
│ --class                   TEXT               Free-form software class;      │
│                                              built-ins include application, │
│                                              service, driver, utility,      │
│                                              runtime, os_builtin.           │
│ --vendor                  TEXT               Software vendor.               │
│ --command                 TEXT               Fixed launch command.          │
│ --device-class            TEXT               Device class (repeatable).     │
│ --zone                    TEXT               Defined Zone tag (repeatable). │
│ --path                    TEXT               Published anchor NAME=LOCATION │
│                                              (repeatable).                  │
│ --definition-file         FILE               YAML/JSON entry for detection  │
│                                              rules, relationships, or full  │
│                                              authoring.                     │
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software delete

 Usage: pinman software delete [OPTIONS] NAME

 Delete a catalog definition and report/clean active references.
 Historical capture rows keep their recorded Software metadata. A real
 deletion requires confirmation or `--force`; detected availability state for
 this catalog ID is deleted with the definition.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software detect

 Usage: pinman software detect [OPTIONS]

 Detect software availability on the system.
 Scans for known software using Uninstall registry keys, filesystem presence,
 and running processes. Results are persisted to the catalog.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software edit

 Usage: pinman software edit [OPTIONS] NAME

 Edit authored catalog fields while preserving detected machine state.
 Field options patch the current definition. `--definition-file` performs a
 complete authored-field replacement; neither mode changes available, version,
 resolved executable paths, timestamps, or detection evidence.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --label                        TEXT               Replace the catalog       │
│                                                   label.                    │
│ --class                        TEXT               Replace the free-form     │
│                                                   software class.           │
│ --vendor                       TEXT               Replace the vendor.       │
│ --clear-vendor                                    Remove the vendor.        │
│ --command                      TEXT               Replace the fixed launch  │
│                                                   command.                  │
│ --clear-command                                   Remove the fixed launch   │
│                                                   command.                  │
│ --device-class                 TEXT               Replace device classes.   │
│ --clear-device-classes                            Remove all device         │
│                                                   classes.                  │
│ --zone                         TEXT               Replace Zone tags.        │
│ --clear-zones                                     Remove all Zone tags.     │
│ --path                         TEXT               Replace paths with        │
│                                                   NAME=LOCATION values.     │
│ --clear-paths                                     Remove all published      │
│                                                   paths.                    │
│ --definition-file              FILE               Atomically replace all    │
│                                                   authored catalog fields   │
│                                                   from YAML/JSON.           │
│ --dry-run                                         Preview what would change │
│                                                   without applying it.      │
│ --output                -o     [human|json|yaml]  Output format (human |    │
│                                                   json | yaml). [default:   │
│                                                   human]                    │
│ --verbose/--quiet       -v/-q                     Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                  -h,-?                     Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software export

 Usage: pinman software export [OPTIONS] NAME

 Export one catalog definition in reusable `software:` schema shape.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --file                    FILE               Write the reusable definition  │
│                                              to a YAML or JSON file.        │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software launch

 Usage: pinman software launch [OPTIONS] NAME

 Launch an external software/tool by name, label, or numeric ID.
 NAME may be the label shown by 'software list', a catalog name, or a numeric
 ID. Mirrors the UI's one-click launch on the Software tab / device drawer —
 run a tool on the machine over SSH. Fails (exit 1) if no launch command
 resolves.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software list

 Usage: pinman software list [OPTIONS]

 List detected software from the catalog.
 Shows software previously detected by 'pinman software detect'. By default
 shows only available software; pass --all to include unavailable entries.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --all                                        Include unavailable entries.   │
│ --class                   TEXT               Filter by exact software class │
│                                              (free-form).                   │
│ --group-by                [group|class]      Group human output by catalog  │
│                                              group or software class.       │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software reset

 Usage: pinman software reset [OPTIONS]

 Clear detected machine state without deleting catalog definitions.
 Preserves every authored Software definition, including detection rules and
 path defaults. Run `software detect` afterward to scan again.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f     Skip the confirmation prompt (and authorize the   │
│                           op when non-interactive).                         │
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman software show

 Usage: pinman software show [OPTIONS] NAME

 Show detail for one catalog entry by name, label, or numeric ID.
 NAME may be the label shown by 'software list', a catalog name, or a numeric
 ID.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  NAME  TEXT  [required]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman status

 Usage: pinman status [OPTIONS]

 Show this machine's Overview: identity, services + health rollup.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --check                                      Run a live status check first  │
│                                              (device re-probe + profile     │
│                                              value refresh).                │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system

 Usage: pinman system [OPTIONS] COMMAND [ARGS]...

 This machine's system information (Machine > System).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Host ──────────────────────────────────────────────────────────────────────┐
│ show     Show basic host identity (hostname, IP, OS).                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Reachability ──────────────────────────────────────────────────────────────┐
│ check  Check whether this machine is reachable from other devices on the    │
│        LAN.                                                                 │
│ qr     Show a QR code to connect another device to this machine.            │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ firewall  Open or close Windows Firewall access to Pinman from other        │
│           devices.                                                          │
│ port      Show or set the TCP port Pinman's services listen on.             │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system check

 Usage: pinman system check [OPTIONS]

 Check whether this machine is reachable from other devices on the LAN.
 Reports whether the Windows firewall allows inbound traffic on the API port —
 the usual reason a phone or another PC can't connect even though Pinman is
 running here. For whether Pinman itself is up, use `pinman service status`.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --port                    INTEGER            TCP port to check for LAN      │
│                                              reachability. [default: 7466]  │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system firewall

 Usage: pinman system firewall [OPTIONS] [[on|off]]

 Open or close Windows Firewall access to Pinman from other devices.
 With no argument, shows whether the pinman rule exists. ``on`` creates the
 "Pinman Server" inbound TCP allow rule — the same rule the installer's
 firewall option creates (re-running replaces it); ``off`` removes it.
 Changing the rule requires an administrator terminal. Browsing on this
 machine itself never needs this — Windows does not firewall loopback.
 ``--no-verify`` skips the reachability confirmation. That check runs ``netsh
 advfirewall firewall show rule name=all verbose``, which takes seconds on a
 machine with many rules — fine interactively, but the installer runs this
 hidden and would just appear to hang.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ STATE  [[on|off]]                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --port                       INTEGER            TCP port the firewall rule  │
│                                                 allows. [default: 7466]     │
│ --profiles                   TEXT               Firewall profile(s) for the │
│                                                 rule, comma-separated:      │
│                                                 domain, private, public.    │
│                                                 [default: private]          │
│ --verify/--no-verify                            Confirm reachability        │
│                                                 afterwards (enumerates      │
│                                                 every firewall rule; slow). │
│ --output              -o     [human|json|yaml]  Output format (human | json │
│                                                 | yaml). [default: human]   │
│ --verbose/--quiet     -v/-q                     Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│ --help                -h,-?                     Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system port

 Usage: pinman system port [OPTIONS] [BASE_PORT]

 Show or set the TCP port Pinman's services listen on.
 With no argument, shows the base port and every service's derived port. Given
 a number, sets the base port: the API listens there and each sidecar takes
 the next port up, so one number moves the whole fleet off a busy port.
 The setting is machine-level (not per project) — all five processes must
 agree — so changing it takes effect on the next restart, and the firewall
 rule, being port-scoped, must be re-created to match.
 Each port is also tested for availability, so this is the command that
 answers "why won't that service start?". Setting a base whose block is
 already taken by another program is refused unless --force.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ BASE_PORT  INTEGER                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force                                      Set the port even if another   │
│                                              program already holds one of   │
│                                              the block.                     │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system qr

 Usage: pinman system qr [OPTIONS]

 Show a QR code to connect another device to this machine.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --timeout                 INTEGER  Seconds before the QR popup auto-closes  │
│                                    (0 = stay open until closed). [default:  │
│                                    0]                                       │
│ --size                    INTEGER  QR code size in pixels. [default: 170]   │
│ --verbose/--quiet  -v/-q           Echo/hide detailed output incl. progress │
│                                    logs (applies to the whole run; default  │
│                                    quiet — PINMAN_VERBOSE env var sets the  │
│                                    default).                                │
│ --help             -h,-?           Show this message and exit.              │
└─────────────────────────────────────────────────────────────────────────────┘

pinman system show

 Usage: pinman system show [OPTIONS]

 Show basic host identity (hostname, IP, OS).
 Minimal stub — the full Machine > System view (OS settings) is surfaced via
 `pinman winrt`; a dedicated system-info aggregator is a gap.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag

 Usage: pinman tag [OPTIONS] COMMAND [ARGS]...

 Tag definition management commands.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Tags ──────────────────────────────────────────────────────────────────────┐
│ list       List all defined zone tags.                                      │
│ create     Create a new zone tag definition.                                │
│ rename     Rename a zone tag and propagate to all items.                    │
│ delete     Delete a zone tag definition.                                    │
│ import     Import zone tag definitions from a YAML file.                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ show      Show one Zone definition using case-insensitive lookup.           │
│ update    Update or explicitly clear Zone display metadata.                 │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag create

 Usage: pinman tag create [OPTIONS] FULLNAME

 Create a new zone tag definition.
 FULLNAME uses ``category:name`` syntax (e.g., Audio, Audio:Music).
 Examples:
     pinman tag create Audio
     pinman tag create Audio:Music --label "Game Music"

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FULLNAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --label                   TEXT               Display label                  │
│ --description             TEXT               Description                    │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag delete

 Usage: pinman tag delete [OPTIONS] FULLNAME

 Delete a zone tag definition.
 Removes the tag from schema items by default, preserving historical tag data
 on captures; ``--force-all`` also strips it from captures. Destructive, so it
 confirms in a terminal and refuses non-interactively without ``--force`` /
 ``--force-all``.
 Examples:
     pinman tag delete Audio
     pinman tag delete Audio --force
     pinman tag delete Audio --force-all

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FULLNAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run                                    Preview what would change      │
│                                              without applying it.           │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --force-all                                  Also remove the tag from ALL   │
│                                              items including captures (not  │
│                                              just schema items).            │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag import

 Usage: pinman tag import [OPTIONS] FILE_PATH

 Import zone tag definitions from a YAML file.
 Example YAML format:
 zone_defs:
   - category: Audio
   - category: Audio
     name: Music
     label: Game Music

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FILE_PATH  FILE  [required]                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --replace                                    Update existing tag            │
│                                              definitions instead of         │
│                                              skipping them.                 │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag list

 Usage: pinman tag list [OPTIONS]

 List all defined zone tags.
 By default, shows tag definitions. Use ``--scan`` to show actual tags on
 items, highlighting any that don't have definitions (orphaned tags).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --tree                                       Display hierarchically by      │
│                                              category                       │
│ --scan                                       Scan items for actual tags     │
│                                              (not just definitions)         │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag rename

 Usage: pinman tag rename [OPTIONS] OLD_FULLNAME NEW_FULLNAME

 Rename a zone tag and propagate to all items.
 Works for both defined tags (with definitions) and orphan tags (tags on items
 without definitions). Renaming is non-destructive, so it runs without a
 confirmation prompt.
 Examples:
     pinman tag rename Audio Sound
     pinman tag rename Audio:Music Audio:Soundtrack

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  OLD_FULLNAME  TEXT  [required]                                           │
│ *  NEW_FULLNAME  TEXT  [required]                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag show

 Usage: pinman tag show [OPTIONS] FULLNAME

 Show one Zone definition using case-insensitive lookup.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FULLNAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tag update

 Usage: pinman tag update [OPTIONS] FULLNAME

 Update or explicitly clear Zone display metadata.
 This does not rename the tag or change its uses; use `tag rename` for that.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  FULLNAME  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --label                     TEXT               Replace the display label.   │
│ --clear-label                                  Remove the display label.    │
│ --description               TEXT               Replace the description.     │
│ --clear-description                            Remove the description.      │
│ --dry-run                                      Preview what would change    │
│                                                without applying it.         │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial

 Usage: pinman tutorial [OPTIONS] COMMAND [ARGS]...

 Manage pinman tutorials (seed + step disposable teaching projects).

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Tutorials ─────────────────────────────────────────────────────────────────┐
│ list     List installable tutorials (bundled + installed) and the projects  │
│          seeded from them.                                                  │
│ install  Seed a project from a tutorial (bundled/installed id, or a         │
│          tutorial directory path).                                          │
│ drift    Apply DRIFT — a change to the tutorial's world, as if it happened  │
│          behind Pinman's back.                                              │
│ goto     Re-seed a tutorial-backed project to CHAPTER's starting state, or  │
│          list the chapters.                                                 │
│ docs     Open a tutorial's installed offline docs (default: the guide).     │
│ demo     Open the Pinman Demo Manager, a window for driving a tutorial's    │
│          chapters.                                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Authoring ─────────────────────────────────────────────────────────────────┐
│ verify   Authoring QA: does this project match what `goto CHAPTER` would    │
│          produce?                                                           │
│ package  Build tutorial TUTORIAL into a distributable                       │
│          <id>-tutorial-<version>.zip.                                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ scene   Read a demo scene's current values from a tutorial-backed project.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial demo

 Usage: pinman tutorial demo [OPTIONS]

 Open the Pinman Demo Manager, a window for driving a tutorial's chapters.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial docs

 Usage: pinman tutorial docs [OPTIONS] [TUTORIAL] [DOC]

 Open a tutorial's installed offline docs (default: the guide).
 With no TUTORIAL, uses the tutorial that seeded --project (or the active
 project). DOC picks a shipped doc by name (extension optional; html wins over
 md): html opens in your browser, markdown renders in the terminal. The guide
 is a self-contained local HTML file and needs no network connection.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TUTORIAL_ID  [TUTORIAL]                                                     │
│ DOC          TEXT                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Tutorial-backed project        │
│                                              (default: active).             │
│ --no-open                                    Print the doc path without     │
│                                              opening it.                    │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial drift

 Usage: pinman tutorial drift [OPTIONS] [DRIFT]

 Apply DRIFT — a change to the tutorial's world, as if it happened behind
 Pinman's back.
 Edits source files, plus machine state (registry keys, system audio) where
 the story calls for it. Nothing is refreshed or captured for you: that's your
 move — run a refresh or take a capture afterward and watch the drift surface
 in Pinman.
 Applies only that drift, on top of wherever the project is now. Your captures
 and history are untouched and Pinman can keep running. If the files it
 changes were edited by hand, it stops without writing anything and points you
 at `pinman tutorial goto`.
 DRIFT is a drift name, or a chapter name/number — a chapter that performs
 several drifts applies them all, in order. With no DRIFT, lists the chapters
 declared by the project's origin tutorial with their drifts, numbered.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ DRIFT  [DRIFT]                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Project to drift (default:     │
│                                              active).                       │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial goto

 Usage: pinman tutorial goto [OPTIONS] [CHAPTER]

 Re-seed a tutorial-backed project to CHAPTER's starting state, or list the
 chapters.
 For joining a tutorial part-way through: the project is wiped and rebuilt,
 then the tutorial replays the earlier chapters' Pinman work and drift, so you
 land where a learner who did them by hand would be. **This discards the work
 you have done** — to advance without losing it, use `pinman tutorial drift`.
 With no CHAPTER, lists the chapters declared by the project's origin
 tutorial, numbered. CHAPTER is a chapter name or one of those numbers.
 Re-seeding offers to stop the tray and its services first — the seed leaves
 the target active, and a server left running would keep serving its old one.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ CHAPTER  TEXT                                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Project to re-seed (default:   │
│                                              active).                       │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial install

 Usage: pinman tutorial install [OPTIONS] [TUTORIAL]

 Seed a project from a tutorial (bundled/installed id, or a tutorial directory
 path).
 Idempotent: re-running re-seeds the same project to baseline. Destructive on
 the target project (its home is wiped and re-seeded). Seeding any project
 offers to stop the tray and its services first — the seed leaves the target
 active, and a server left running would keep serving its old one.
 With no TUTORIAL, lists the installable tutorials (same as `tutorial list`).

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TUTORIAL  [TUTORIAL]                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Target project (default: the   │
│                                              tutorial id).                  │
│ --force            -f                        Skip the confirmation prompt   │
│                                              (and authorize the op when     │
│                                              non-interactive).              │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial list

 Usage: pinman tutorial list [OPTIONS]

 List installable tutorials (bundled + installed) and the projects seeded from
 them.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial package

 Usage: pinman tutorial package [OPTIONS] TUTORIAL

 Build tutorial TUTORIAL into a distributable <id>-tutorial-<version>.zip.
 Author-time only. drifts/ ships (the learner runs those scripts); __pycache__
 and docs/authoring/ are excluded.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  TUTORIAL  TEXT  [required]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --version                 TEXT               Override the built artifact's  │
│                                              version.                       │
│ --out                     TEXT               Output directory (default:     │
│                                              cwd).                          │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial scene

 Usage: pinman tutorial scene [OPTIONS] DRIFT

 Read a demo scene's current values from a tutorial-backed project.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  DRIFT  TEXT  [required]                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                 TEXT               Tutorial-backed project        │
│                                              (default: active).             │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman tutorial verify

 Usage: pinman tutorial verify [OPTIONS] CHAPTER

 Authoring QA: does this project match what `goto CHAPTER` would produce?
 Walk a chapter by hand, then verify before writing the next one. It
 fingerprints your project, replays `seed.py` to CHAPTER in a throwaway
 project, and reports every difference — so a guide whose steps have drifted
 from the seed recipe fails here instead of under a learner weeks later.
 Read-only on your machine and your project: the replay runs with machine
 drift suppressed, and the scratch project is always removed. Chapters declare
 machine state through `expect_machine()`, which is checked live — a
 differential cannot see it, since both projects share one registry.
 Declines outright once a `verify.self_contained` chapter falls behind
 CHAPTER: seed.py never replays one, so the diff would be its whole content.
 Exits non-zero on any difference.

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  CHAPTER  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --project                   TEXT               Project to verify (default:  │
│                                                active).                     │
│ --include-untracked                            Compare untracked items too  │
│                                                (for tutorials that teach    │
│                                                discovery).                  │
│ --force              -f                        Skip the confirmation prompt │
│                                                (and authorize the op when   │
│                                                non-interactive).            │
│ --output             -o     [human|json|yaml]  Output format (human | json  │
│                                                | yaml). [default: human]    │
│ --verbose/--quiet    -v/-q                     Echo/hide detailed output    │
│                                                incl. progress logs (applies │
│                                                to the whole run; default    │
│                                                quiet — PINMAN_VERBOSE env   │
│                                                var sets the default).       │
│ --help               -h,-?                     Show this message and exit.  │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg

 Usage: pinman winreg [OPTIONS] COMMAND [ARGS]...

 Windows registry power tools (show, search, extract, diff, blacklist…).
 A CLI-only superset of the UI. Reads the live registry or cached `.reg`
 dumps; the `blacklist` and `discover` sub-groups manage filtering patterns
 and before/after change discovery.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Inspect ───────────────────────────────────────────────────────────────────┐
│ show       Display a winreg key's values and subkeys.                       │
│ search     Search for keys/values matching a pattern.                       │
│ inventory  List winreg: entries from the schema and check if they exist on  │
│            the system.                                                      │
│ stats      Show winreg statistics.                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Extract & Diff ────────────────────────────────────────────────────────────┐
│ extract       Extract winreg to .reg files.                                 │
│ diff          Compare winreg data between files or against live winreg.     │
│ watch         Watch registry changes around an action.                      │
│ clear-cache   Delete winreg pickle sidecars in the live extract directory.  │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Sub-groups ────────────────────────────────────────────────────────────────┐
│ discover   Discover registry changes by comparing before/after extractions. │
│ blacklist  Manage and validate winreg blacklist patterns.                   │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist

 Usage: pinman winreg blacklist [OPTIONS] COMMAND [ARGS]...

 Manage and validate winreg blacklist patterns.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Patterns ──────────────────────────────────────────────────────────────────┐
│ list        List all blacklist key and value patterns.                      │
│ add         Add a pattern to the global blacklist.                          │
│ remove      Remove a pattern from the global blacklist.                     │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Analyze ───────────────────────────────────────────────────────────────────┐
│ test      Test what a pattern matches against cached extraction data.       │
│ audit     Coverage report for blacklist patterns against cached extraction  │
│           data.                                                             │
│ optimize  Remove redundant patterns covered by a broader wildcard.          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Export ────────────────────────────────────────────────────────────────────┐
│ export      Export blacklist patterns filtered by scope.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist add

 Usage: pinman winreg blacklist add [OPTIONS] PATTERN

 Add a pattern to the global blacklist.
 PATTERN: fnmatch wildcards or regex with a 're:' prefix.
 Examples:
     pinman winreg blacklist add "*Cache*" --comment "Exclude cache keys"
     pinman winreg blacklist add "*Timestamp*" --type value
     pinman winreg blacklist add "re:.*MRU.*" --type key --comment "MRU lists"

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PATTERN  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type                    [key|value]   Pattern type (key or value).        │
│ --comment                 TEXT          Comment explaining the pattern.     │
│ --force            -f                   Skip the confirmation prompt (and   │
│                                         authorize the op when               │
│                                         non-interactive).                   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist audit

 Usage: pinman winreg blacklist audit [OPTIONS]

 Coverage report for blacklist patterns against cached extraction data.
 Per-pattern hit counts (effectiveness) and dead patterns (no matches on this
 machine). Requires cached extraction data — run 'pinman winreg extract
 --no-filter' first if none exists.
 Examples:
     pinman winreg blacklist audit
     pinman winreg blacklist audit --hive HKCU
     pinman winreg blacklist audit --file report.json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive                    [HKCU|HKLM|all]  Which hive(s) to audit against.  │
│ --file                    FILE             Write the payload to this file   │
│                                            as UTF-8 (default: stdout).      │
│ --output           -o     [human|json]     Output format (human | json).    │
│                                            [default: human]                 │
│ --verbose/--quiet  -v/-q                   Echo/hide detailed output incl.  │
│                                            progress logs (applies to the    │
│                                            whole run; default quiet —       │
│                                            PINMAN_VERBOSE env var sets the  │
│                                            default).                        │
│ --help             -h,-?                   Show this message and exit.      │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist export

 Usage: pinman winreg blacklist export [OPTIONS]

 Export blacklist patterns filtered by scope.
 Useful for distributing a starter blacklist containing only patterns safe for
 all machines (scope: universal).
 Examples:
     pinman winreg blacklist export                       # stdout
     pinman winreg blacklist export --file starter.jsonc  # file

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --scope                   [universal|system|candi  Filter by scope.         │
│                           date|all]                Default: universal (for  │
│                                                    distribution).           │
│ --file                    FILE                     Write the payload to     │
│                                                    this file as UTF-8       │
│                                                    (default: stdout).       │
│ --output           -o     [human|json]             Output format (human |   │
│                                                    json). [default: human]  │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist list

 Usage: pinman winreg blacklist list [OPTIONS]

 List all blacklist key and value patterns.
 Examples:
 pinman winreg blacklist list
 pinman winreg blacklist list -o json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist optimize

 Usage: pinman winreg blacklist optimize [OPTIONS]

 Remove redundant patterns covered by a broader wildcard.
 A pattern is redundant if a broader wildcard already covers it (e.g. with
 'Software\Microsoft\*' present, 'Software\Microsoft\Windows\*' is redundant).
 Use --dry-run to preview; otherwise the removal is applied (force-gated).
 Examples:
     pinman winreg blacklist optimize --dry-run   # preview redundant
     pinman winreg blacklist optimize             # remove (prompts)
     pinman winreg blacklist optimize --force      # remove (scripted)

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --blacklist-file          PATH          Path to blacklist file. Default:    │
│                                         reference/winreg_blacklist.json[c]. │
│ --dry-run                               Preview what would change without   │
│                                         applying it.                        │
│ --force            -f                   Skip the confirmation prompt (and   │
│                                         authorize the op when               │
│                                         non-interactive).                   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist remove

 Usage: pinman winreg blacklist remove [OPTIONS] PATTERN

 Remove a pattern from the global blacklist.
 PATTERN: the exact pattern to remove.
 Examples:
     pinman winreg blacklist remove "*Cache*"
     pinman winreg blacklist remove "*Timestamp*" --type value

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PATTERN  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type                    [key|value]   Pattern type (key or value).        │
│ --force            -f                   Skip the confirmation prompt (and   │
│                                         authorize the op when               │
│                                         non-interactive).                   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg blacklist test

 Usage: pinman winreg blacklist test [OPTIONS] PATTERN

 Test what a pattern matches against cached extraction data.
 Shows how many keys/values a pattern would match, with sample matches.
 Requires cached extraction data — run 'pinman winreg extract --no-filter'
 first if none exists.
 Examples:
     pinman winreg blacklist test "*\Classes\CLSID\*"
     pinman winreg blacklist test "*LastChecked*" --type value
     pinman winreg blacklist test "*\SolidWorks\*" --hive HKCU

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  PATTERN  TEXT  [required]                                                │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type                    [key|value]      Pattern type (key or value).     │
│ --hive                    [HKCU|HKLM|all]  Which hive(s) to test against.   │
│ --limit                   INTEGER          Max matches to display.          │
│ --output           -o     [human|json]     Output format (human | json).    │
│                                            [default: human]                 │
│ --verbose/--quiet  -v/-q                   Echo/hide detailed output incl.  │
│                                            progress logs (applies to the    │
│                                            whole run; default quiet —       │
│                                            PINMAN_VERBOSE env var sets the  │
│                                            default).                        │
│ --help             -h,-?                   Show this message and exit.      │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg clear-cache

 Usage: pinman winreg clear-cache [OPTIONS]

 Delete winreg pickle sidecars in the live extract directory.
 Each `.reg`/`.hiv` file in `extract/winreg/` has a `.pkl` sidecar that caches
 the parsed data so subsequent reads skip the parser. This deletes those
 sidecars; the next read regenerates them.
 Backup directories (`backup_NNN/winreg/`) are *not* touched — those sidecars
 are backed up alongside their `.reg` files.
 Use when forcing a fresh parse (e.g. after editing a source `.reg` without
 bumping its mtime) or reclaiming disk space.
 Examples:
     pinman winreg clear-cache
     pinman winreg clear-cache --force

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force            -f                   Skip the confirmation prompt (and   │
│                                         authorize the op when               │
│                                         non-interactive).                   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg diff

 Usage: pinman winreg diff [OPTIONS] SOURCE [TARGET]

 Compare winreg data between files or against live winreg.
 SOURCE: Path to first .reg file
 TARGET: Path to second .reg file (or omit if using --live)


 Examples:
     pinman winreg diff file1.reg file2.reg
     pinman winreg diff backup.reg --live
     pinman winreg diff old.reg new.reg -o json
     pinman winreg diff old.reg new.reg -o json --file changes.json

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  SOURCE  PATH  [required]                                                 │
│    TARGET  PATH                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --live                                          Compare source file against │
│                                                 live winreg.                │
│ --hive                    [HKCU|HKLM|HKCR|HKU]  Hive to compare when using  │
│                                                 --live (auto-detected if    │
│                                                 not specified).             │
│ --values-only                                   Only show value             │
│                                                 differences, not key        │
│                                                 differences.                │
│ --file                    FILE                  Write the payload to this   │
│                                                 file as UTF-8 (default:     │
│                                                 stdout).                    │
│ --output           -o     [human|json]          Output format (human |      │
│                                                 json). [default: human]     │
│ --verbose/--quiet  -v/-q                        Echo/hide detailed output   │
│                                                 incl. progress logs         │
│                                                 (applies to the whole run;  │
│                                                 default quiet —             │
│                                                 PINMAN_VERBOSE env var sets │
│                                                 the default).               │
│ --help             -h,-?                        Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg discover

 Usage: pinman winreg discover [OPTIONS] COMMAND [ARGS]...

 Discover registry changes by comparing before/after extractions.
 Default scope: HKCU\Software (where app settings live).
 Use --hive and --root-key to adjust scope.


 Workflow:
     pinman winreg discover baseline          # Before your change
     <make your change — install, configure, etc.>
     pinman winreg discover changes            # See what changed

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Discovery ─────────────────────────────────────────────────────────────────┐
│ baseline     Take a baseline extraction before making changes.              │
│ changes      Show what changed since the last baseline.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg discover baseline

 Usage: pinman winreg discover baseline [OPTIONS]

 Take a baseline extraction before making changes.
 Overwrites any existing baseline for this hive.
 Examples:
     pinman winreg discover baseline
     pinman winreg discover baseline --root-key "Software\JoyToKey"

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive                    [HKCU|HKLM]   Hive to extract (default: HKCU).    │
│ --root-key                TEXT          Root key within hive (default:      │
│                                         Software).                          │
│ --force            -f                   Skip the confirmation prompt (and   │
│                                         authorize the op when               │
│                                         non-interactive).                   │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg discover changes

 Usage: pinman winreg discover changes [OPTIONS]

 Show what changed since the last baseline.
 Examples:
 pinman winreg discover changes
 pinman winreg discover changes -o json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive                    [HKCU|HKLM]   Hive to compare (default: HKCU).    │
│ --root-key                TEXT          Root key within hive (default:      │
│                                         Software).                          │
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg extract

 Usage: pinman winreg extract [OPTIONS]

 Extract winreg to .reg files.
 By default, extracts full subtree dumps with blacklist filtering. Use
 --tracked-only to extract only schema-tracked keys (fast, <1s).
 With --from-file, filters an existing .reg file instead of extracting from
 the live registry. Useful for post-processing raw dumps.
 Destinations:
     --out DIR        write the .reg file(s) to a directory (default: extract
 dir)
     --out-file PATH  write a single .reg file (single hive / --from-file)


 Modes:
     (default)       Full extraction: dump allowed subtrees with blacklist
 filtering
     --tracked-only  Fast: extract only schema-tracked keys via Python API
     --no-filter     No filtering - extract everything (raw)


 Examples:
     pinman winreg extract --hive HKCU
     pinman winreg extract --hive all --out ./registry_backup
     pinman winreg extract --tracked-only
     pinman winreg extract --hive HKLM --no-filter
     pinman winreg extract --from-file raw_dump.reg --out-file filtered.reg

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive                    [HKCU|HKLM|all]  Winreg hive to extract (default: │
│                                            HKCU). Use 'all' for HKCU and    │
│                                            HKLM.                            │
│ --out                     DIRECTORY        Output DIRECTORY for the .reg    │
│                                            file(s) (default: the extract    │
│                                            dir).                            │
│ --out-file                FILE             Single output .reg file (single  │
│                                            hive / --from-file only).        │
│ --root-key                TEXT             Root key within hive to extract  │
│                                            (e.g., Software/MyApp).          │
│ --tracked-only                             Extract only schema-tracked keys │
│                                            (fast, <1s). Requires schema     │
│                                            context.                         │
│ --no-filter                                Raw mode: skip all blacklist     │
│                                            filtering (extract everything).  │
│ --from-file               FILE             Filter an existing .reg file     │
│                                            instead of extracting from live  │
│                                            registry.                        │
│ --encoding                [utf-8|utf-16]   Output file encoding.            │
│ --output           -o     [human|json]     Output format (human | json).    │
│                                            [default: human]                 │
│ --verbose/--quiet  -v/-q                   Echo/hide detailed output incl.  │
│                                            progress logs (applies to the    │
│                                            whole run; default quiet —       │
│                                            PINMAN_VERBOSE env var sets the  │
│                                            default).                        │
│ --help             -h,-?                   Show this message and exit.      │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg inventory

 Usage: pinman winreg inventory [OPTIONS]

 List winreg: entries from the schema and check if they exist on the system.
 Shows which registry keys defined in your schema are present on the system
 and which are missing from the current machine.
 Examples:
     pinman winreg inventory
     pinman winreg inventory -o json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg show

 Usage: pinman winreg show [OPTIONS] [KEY_PATH]

 Display a winreg key's values and subkeys.
 KEY_PATH: a winreg path like HKCU/Software/MyApp or HKLM/SOFTWARE/Test
 (forward slashes). Omit it to list the available hives.
 Formats (-o):
     human   table of values + subkeys (default)
     json    structured key data
     reg     Windows .reg export text (payload → stdout)


 Examples:
     pinman winreg show HKCU/Software
     pinman winreg show HKLM/SOFTWARE/Microsoft --recursive
     pinman winreg show HKCU/Software/MyApp -o json
     pinman winreg show HKCU/Software/MyApp -o reg

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ KEY_PATH  TEXT                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --recursive                                 Show subkeys recursively.       │
│ --depth                   INTEGER           Max depth for recursive display │
│                                             (default: 1).                   │
│ --output           -o     [human|json|reg]  Output format (human | json |   │
│                                             reg). [default: human]          │
│ --verbose/--quiet  -v/-q                    Echo/hide detailed output incl. │
│                                             progress logs (applies to the   │
│                                             whole run; default quiet —      │
│                                             PINMAN_VERBOSE env var sets the │
│                                             default).                       │
│ --help             -h,-?                    Show this message and exit.     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg stats

 Usage: pinman winreg stats [OPTIONS]

 Show winreg statistics.
 Global blacklist pattern counts, sample live key counts, and the singleton
 schema's tracked winreg item counts.
 Examples:
     pinman winreg stats
     pinman winreg stats -o json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output           -o     [human|json]  Output format (human | json).       │
│                                         [default: human]                    │
│ --verbose/--quiet  -v/-q                Echo/hide detailed output incl.     │
│                                         progress logs (applies to the whole │
│                                         run; default quiet — PINMAN_VERBOSE │
│                                         env var sets the default).          │
│ --help             -h,-?                Show this message and exit.         │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winreg watch

 Usage: pinman winreg watch [OPTIONS]

 Watch registry changes around an action.
 Takes a before/after raw registry dump and shows what changed. Use --command
 to run an automated action, or --pause to wait for a manual action.
 Modes:
     --command  Run a shell command between dumps
     --pause    Pause for manual action (press Enter to continue)


 Output structure (in extract/watch/):
     {hint}_{timestamp}/
         HKEY_CURRENT_USER_raw_before.reg
         HKEY_CURRENT_USER_raw_after.reg


 Examples:
     pinman winreg watch --command "pinman profile apply 'Config B'"
     pinman winreg watch --pause --label "change-resolution"
     pinman winreg watch --command "my_script.bat" --hive all
     pinman winreg watch --command "..." -o json

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive                           [HKCU|HKLM|all]  Registry hive to watch    │
│                                                   (default: HKCU). Use      │
│                                                   'all' for both.           │
│ --command                        TEXT             Command to run between    │
│                                                   before/after dumps.       │
│ --pause                                           Pause mode: wait for      │
│                                                   manual action instead of  │
│                                                   running a command.        │
│ --label                          TEXT             Label for output          │
│                                                   directory (overrides      │
│                                                   auto-derived hint from    │
│                                                   command).                 │
│ --out                            DIRECTORY        Parent DIRECTORY for      │
│                                                   watch output (default:    │
│                                                   extract/watch/).          │
│ --values-only                                     Only show value           │
│                                                   differences, not key      │
│                                                   differences.              │
│ --keep-dumps/--no-keep-d                          Keep dump files after     │
│ umps                                              watch completes (default: │
│                                                   keep).                    │
│ --output                  -o     [human|json]     Output format (human |    │
│                                                   json). [default: human]   │
│ --verbose/--quiet         -v/-q                   Echo/hide detailed output │
│                                                   incl. progress logs       │
│                                                   (applies to the whole     │
│                                                   run; default quiet —      │
│                                                   PINMAN_VERBOSE env var    │
│                                                   sets the default).        │
│ --help                    -h,-?                   Show this message and     │
│                                                   exit.                     │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winrt

 Usage: pinman winrt [OPTIONS] COMMAND [ARGS]...

 Windows Runtime (winrt:) settings commands.

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet  -v/-q  Echo/hide detailed output incl. progress logs     │
│                           (applies to the whole run; default quiet —        │
│                           PINMAN_VERBOSE env var sets the default).         │
│ --help             -h,-?  Show this message and exit.                       │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ WinRT ─────────────────────────────────────────────────────────────────────┐
│ extract    Extract live WinRT settings to a JSON snapshot file.             │
│ diff       Compare WinRT JSON files or against live settings.               │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winrt diff

 Usage: pinman winrt diff [OPTIONS] SOURCE [TARGET]

 Compare WinRT JSON files or against live settings.
 SOURCE: Path to first JSON file
 TARGET: Path to second JSON file (or omit if using --live)


 Examples:
     pinman winrt diff backup.json --live
     pinman winrt diff old.json new.json
     pinman winrt diff backup.json --live -o json

┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ *  SOURCE  PATH  [required]                                                 │
│    TARGET  PATH                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --live                                       Compare source file against    │
│                                              live WinRT settings.           │
│ --values-only                                Only show property value       │
│                                              differences.                   │
│ --output           -o     [human|json|yaml]  Output format (human | json |  │
│                                              yaml). [default: human]        │
│ --verbose/--quiet  -v/-q                     Echo/hide detailed output      │
│                                              incl. progress logs (applies   │
│                                              to the whole run; default      │
│                                              quiet — PINMAN_VERBOSE env var │
│                                              sets the default).             │
│ --help             -h,-?                     Show this message and exit.    │
└─────────────────────────────────────────────────────────────────────────────┘

pinman winrt extract

 Usage: pinman winrt extract [OPTIONS]

 Extract live WinRT settings to a JSON snapshot file.
 Writes all 14 Windows Settings categories (sound, display, gaming, GPU,
 power, network, security, services, startup, about, monitoring,
 personalization, accessibility, input) to a snapshot file. With ``-o
 json|yaml`` the extracted data is also emitted to stdout (the file is still
 written; progress goes to stderr).
 Modes:
     (default)       Full extraction: all categories to winrt_settings.json
     --tracked-only  Schema-scoped: tracked paths only to
 winrt_settings_tracked.json


 Examples:
     pinman winrt extract
     pinman winrt extract -o json | jq
     pinman -v winrt extract --category Services
     pinman winrt extract --out my_settings.json
     pinman winrt extract --tracked-only

┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --out                     FILE                     Snapshot destination     │
│                                                    (default:                │
│                                                    {app_data}/extract/winrt │
│                                                    /winrt_settings.json).   │
│ --category                [About|Accessibility|Di  Extract only this        │
│                           splay|Gaming|GPU|Input|  category.                │
│                           Monitoring|Network|Pers                           │
│                           onalization|Power|Secur                           │
│                           ity|Services|Sound|Star                           │
│                           tup]                                              │
│ --tracked-only                                     Extract only             │
│                                                    schema-tracked           │
│                                                    properties (fast).       │
│                                                    Writes                   │
│                                                    winrt_settings_tracked.j │
│                                                    son instead of the full  │
│                                                    file.                    │
│ --output           -o     [human|json|yaml]        Output format (human |   │
│                                                    json | yaml). [default:  │
│                                                    human]                   │
│ --verbose/--quiet  -v/-q                           Echo/hide detailed       │
│                                                    output incl. progress    │
│                                                    logs (applies to the     │
│                                                    whole run; default quiet │
│                                                    — PINMAN_VERBOSE env var │
│                                                    sets the default).       │
│ --help             -h,-?                           Show this message and    │
│                                                    exit.                    │
└─────────────────────────────────────────────────────────────────────────────┘