Pinman CLI Reference
Pinman 2.0.260914-227bbdd-wip Beta — generated 2026-09-14
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, cabinet, playfield, backbox). [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-params TEXT Setup profile params 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-params TEXT Profile param overrides 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. `--force` applies without prompting; `--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. │
│ 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:/vPinball/...', '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 │
│ --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. 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. │
│ --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|cancelled|any] Filter by terminal status. 'any' = completed/failed/cancelled. [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. │
│ --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 Release a stale capture lock (releases the shared capture lock). │
│ 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]
Release a stale capture lock (releases the shared capture lock).
Use this when a capture was interrupted and left a stale lock file behind; the lock prevents new captures from running.
┌─ 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) │
│ --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 only changed items (default) │
│ --tracked Only tracked items │
│ --only [files|data|winreg|winrt] Show only items of 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 │
│ --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. │
│ get Get a specific configuration value. │
│ set Set a configuration value. │
│ env Show the current environment, config files, and database location. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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.
┌─ 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 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 cabinet's physical controls). │
│ message Post, clear, or show the on-screen (backglass) 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 down audio server fails a set (exit 1) but reports ``unavailable``
on a read.
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --volume INTEGER RANGE [0<=x<=100] Set output volume 0–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 [0<=x<=100] Set display brightness 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 cabinet'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 cabinet'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 (backglass) 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|scrolling] How the message is 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 cabinet. 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-only Migrate every project 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.
Bindings live under `pinman device binding`; software links under `pinman device software`.
┌─ 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. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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|other] Device class. [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|other] Filter by device class. │
│ --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 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). │
│ 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").
Destructive + structural: rewrites the schema item's type/structure, moves its children under a {{KEY}} row placeholder, and deletes instance children to force a rescan. Only valid
for ini_section / xml_section items. After converting, 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). │
│ --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] │
│ --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 to descendants with --propagate. Metadata-only — no structural change, so no
re-materialization is needed.
┌─ 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). │
│ --label TEXT New label. │
│ --description TEXT New description. │
│ --zone TAG Replace zone tags (repeatable). │
│ --software ID Replace software refs (repeatable). │
│ --propagate [none|children|all] Propagate tag changes (zones/software) 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/vPinball/VPinballX.ini#Standalone"
┌─ 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 Only changed items (added/modified/removed). │
│ --program TEXT Filter by software/program catalog 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). │
│ --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 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. 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/vPinball/VPinballX.ini#Player/Width" 3840
pinman explore set -- "fs:/C/vPinball/VPinballX.ini#Player/Offset" -1
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * LOCATION TEXT [required] │
│ * VALUE TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --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 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 capture floor doesn't
narrow that lever (nothing to widen); an unavailable one carries the reason. Widen it with `pinman capture broaden --item LOCATION`.
Example:
pinman explore show "fs:C:/vPinball/VPinballX.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 and propagating a property to sibling rows
automatically. After tracking, 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). │
│ --label TEXT Label for the tracked schema item. │
│ --description TEXT Description for the tracked schema item. │
│ --zone TAG Zone tag to set (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, or tags. │
│ delete Delete a journal entry. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ 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.
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * --title TEXT Short title (required). [required] │
│ --note TEXT Optional note / annotation. │
│ --tag TEXT Tag (repeatable: --tag audio --tag install). │
│ --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.
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). │
│ --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, or tags.
Select by positional ID or `--latest` (the newest entry). Only the fields you pass change. Tag semantics: omit `--tag`/`--clear-tags` leaves tags unchanged; one or more `--tag`
REPLACES the tag set; `--clear-tags` sets the tag set to empty. `--tag` and `--clear-tags` are mutually exclusive.
┌─ 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). │
│ --tag TEXT Replace tags with these (repeatable). Omit to leave tags unchanged. │
│ --clear-tags Remove all tags from the entry (mutually exclusive with --tag). │
│ --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 [manual|auto|recording|import] Filter by entry source. │
│ --search TEXT Text search in title / note. │
│ --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 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. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ 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). │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ 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). │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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). │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --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 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 show
Usage: pinman log show [OPTIONS]
Show the application log (optionally filtered by level).
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --level [debug|detail|info|warning|error|critical] Show only lines at this level (e.g. info | debug | 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 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 Windows system ID or a display target ID. 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 Windows system ID (e.g. Port_#0003.Hub_#0002) or a display target ID. 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 configuration profiles.
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, parameters, 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 a switcher .py from multiple preset profiles. │
│ collect Generate a preset .py file from collected items (the UI's "Collect"). │
│ 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 · check · lint. │
│ target Manage a profile's targets: list · add · remove. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ run Run a sequenced profile — its steps, holds and commands, in order. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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.
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --param TEXT Parameter in key=value format. │
│ --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. │
│ --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 collect
Usage: pinman profile collect [OPTIONS] NAME
Generate a preset .py file from collected items (the UI's "Collect").
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * --items TEXT JSON array of {location, value} dicts. [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 a switcher .py from multiple preset profiles.
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * --from TEXT Source profile .py file. [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 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 snapshot 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 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 parameterized profile with 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 preview
Usage: pinman profile preview [OPTIONS] NAME
Preview what applying a profile would change.
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --param TEXT Parameter in key=value format. │
│ --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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --param TEXT Parameter in key=value format. │
│ --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 relink
Usage: pinman profile relink [OPTIONS] OLD_PATH_OR_NAME NEW_PATH
Reattach history after an out-of-band profile rename.
OLD_PATH_OR_NAME may be a profile name (looked up in the registry, expected to show state='missing') or an absolute file path. NEW_PATH is the new file path on disk.
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * OLD_PATH_OR_NAME TEXT [required] │
│ * NEW_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 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 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. │
│ --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.
┌─ 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. │
│ --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, parameters, 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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --param TEXT Parameter in key=value format. │
│ --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. │
│ --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. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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 a specific software (software entry + tagged 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/Visual Pinball' \
-o yaml --file vpx.yaml
pinman schema import vpx.yaml --replace \
--item 'winreg:/HKEY_CURRENT_USER/Software/Visual Pinball'
┌─ 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 kit ``<name>``'s ``schema/`` dir across the kit roots.
Catalog-only files (software: without items:) upsert SoftwareProgram 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. (``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] 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 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 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|scheduler} [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 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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --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 the software catalog: 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 program by name, label, or numeric ID. │
│ detect Detect installed pinball software on the system. │
│ launch Launch an external software/tool by name, label, or numeric ID. │
│ reset Clear all software detection records from the catalog. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
pinman software detect
Usage: pinman software detect [OPTIONS]
Detect installed pinball software 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 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 cabinet tool 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 installed software; pass --all to include not-found entries.
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --all Include not-installed entries. │
│ --class [emulator|frontend|driver|utility|runtime|os_builtin] Filter by program 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 all software detection records from the catalog.
Removes all SoftwareProgram records. Run 'pinman software detect' afterward to re-scan from scratch.
┌─ 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 program 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). │
│ --profile TEXT Profile name for the drift count (repeatable; stands in for the UI's pinned list). │
│ --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. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --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 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). │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Authoring ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ verify Authoring QA: does this project match what `goto CHAPTER` would produce? │
│ package Build tutorial TUTORIAL into a distributable <id>-tutorial-<version>.zip. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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 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. │
│ check Check for conflicts between tracked items and the global blacklist. │
│ 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 check
Usage: pinman winreg blacklist check [OPTIONS]
Check for conflicts between tracked items and the global blacklist.
Identifies winreg items tracked in the singleton schema that would be blocked by a blacklist pattern. With --fix, removes the offending patterns (force-gated).
Examples:
pinman winreg blacklist check
pinman winreg blacklist check --fix
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --fix Remove the conflicting patterns from the blacklist. │
│ --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 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|candidate|all] Filter by scope. 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 (software not installed).
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 search
Usage: pinman winreg search [OPTIONS] PATTERN
Search for keys/values matching a pattern.
PATTERN: Wildcard pattern (* and ?) or regex (with --regex flag).
Input files:
Live Windows Registry (default)
extract/winreg/HKEY_*.reg (with --use-cache)
Examples:
pinman winreg search "*Visual*"
pinman winreg search "vpinball" --hive HKLM --root-key SOFTWARE
pinman winreg search ".*[Pp]ath.*" --regex --data
pinman winreg search "*" --keys-only --max-results 50
pinman winreg search "*Visual*" --use-cache # uses cached .reg files
pinman winreg search "*Visual*" -o json
┌─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM|HKCR|HKU|all] Winreg hive to search (default: HKCU). │
│ --root-key TEXT Root key to start search (default: Software). │
│ --keys-only Only search key names. │
│ --values-only Only search value names. │
│ --data Also search value data (slower). │
│ --regex Interpret pattern as regex. │
│ --max-results INTEGER Maximum results to return (default: 100). │
│ --max-depth INTEGER Maximum depth to search (default: 10). │
│ --use-cache Search cached .reg files from default extract location (faster). │
│ --from-file PATH Search keys from a specific .reg file. │
│ --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 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-dumps Keep dump files after 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|Display|Gaming|GPU|Input|Monitoring|Network|Personaliz Extract only this category. │
│ ation|Power|Security|Services|Sound|Startup] │
│ --tracked-only Extract only schema-tracked properties (fast). Writes │
│ winrt_settings_tracked.json 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. │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘