Pinman CLI Reference
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. 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 `readonly_mode` 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 readonly_mode 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 bundle
Usage: pinman bundle [OPTIONS] COMMAND [ARGS]...
Manage bundle instances (the UI's "Games"): list, detect, install, package.
A bundle instance is one detected game in the registry. ``pinman game …`` is
an alias for ``pinman bundle …``.
┌─ 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 detected bundle instances (games) from the registry. │
│ show Show detail for one bundle instance by registry ID. │
│ detect Detect bundle instances (games) from the latest capture. │
│ edit Edit identity fields of a bundle instance. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Packaging ─────────────────────────────────────────────────────────────────┐
│ install Install a bundle package onto this system. │
│ uninstall Uninstall a bundle instance from the registry. │
│ package Package a bundle instance into a portable directory. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle detect
Usage: pinman bundle detect [OPTIONS]
Detect bundle instances (games) from the latest capture.
Scans the capture tree for files matching the bundle kind's schema-declared
detection pattern. Requires a capture to exist.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --kind TEXT Bundle kind to detect. │
│ --pretend Preview without persisting. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle edit
Usage: pinman bundle edit [OPTIONS] BUNDLE_ID
Edit identity fields of a bundle instance.
Examples:
pinman bundle edit 42 --name "Medieval Madness (Williams 1997)"
pinman bundle edit 42 --rom mm_109c --manufacturer Williams --year 1997
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * BUNDLE_ID INTEGER [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --name TEXT Set display name. │
│ --rom TEXT Set ROM name. │
│ --short-name TEXT Set short name. │
│ --manufacturer TEXT Set manufacturer. │
│ --year INTEGER Set year. │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle install
Usage: pinman bundle install [OPTIONS] PACKAGE_PATH
Install a bundle package onto this system.
Reads manifest.yaml from the package, copies files to their target locations,
and merges structured items (registry, INI).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PACKAGE_PATH PATH [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run Preview without making │
│ changes. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle list
Usage: pinman bundle list [OPTIONS]
List detected bundle instances (games) from the registry.
Shows bundle instances previously detected by 'pinman bundle detect'.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --kind TEXT Filter by bundle kind (e.g. │
│ vpxgame). │
│ --status [present|missing] Filter by status. │
│ --search TEXT Search by name/ROM. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle package
Usage: pinman bundle package [OPTIONS] BUNDLE_ID
Package a bundle instance into a portable directory.
Exports all files and structured data referenced by the bundle tree into a
self-contained directory (with manifest.yaml). ``--out`` is the destination
DIRECTORY (a portable package), not a single-file payload.
Examples:
pinman bundle package 42 --out C:/exports/medieval-madness
pinman bundle package 42 --out C:/exports/mm --zip --omit "roms/"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * BUNDLE_ID INTEGER [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --out PATH Output directory for the │
│ portable package. │
│ [required] │
│ --zip Create a zip archive. │
│ --omit TEXT Pattern for refs to omit │
│ (e.g. 'roms/'). │
│ --notes TEXT Notes to include in the │
│ manifest. │
│ --capture-id INTEGER Specific capture to export │
│ from. │
│ --capture Take a fresh capture first. │
│ --output -o [human|json|yaml] Output format (human | json │
│ | yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole run; │
│ default quiet — │
│ PINMAN_VERBOSE env var sets │
│ the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman bundle show
Usage: pinman bundle show [OPTIONS] BUNDLE_ID
Show detail for one bundle instance by registry ID.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * BUNDLE_ID INTEGER [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 bundle uninstall
Usage: pinman bundle uninstall [OPTIONS] BUNDLE_ID
Uninstall a bundle instance from the registry.
This removes the registry entry only — no files are deleted.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * BUNDLE_ID INTEGER [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 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). │
│ cleanup Bulk-delete captures matching filters (chain-safe). │
│ 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 Explorer ribbon'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 to the capture's row. │
│ 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]
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. `--source head` (default) inspects
the head; `--source <id>` inspects a stored capture. 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.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --source TEXT Capture to inspect: a capture │
│ ID, or 'head' (the head). │
│ [default: head] │
│ --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 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' │
│ (no source), a capture │
│ ID, or 'any'. [default: │
│ any] │
│ --reference TEXT Filter by reference │
│ capture ID, or 'any'. │
│ [default: any] │
│ --backup [true|false|any] Filter by │
│ backed-up-bytes kind: │
│ 'true' │
│ (savepoints/backups │
│ only), 'false' │
│ (non-backed up only), │
│ 'any' (no filter). │
│ [default: false] │
│ --older-than TEXT Only captures created │
│ before this age (e.g. │
│ 90d, 6mo, 1y). │
│ --status [completed|failed|cance Filter by terminal │
│ lled|any] status. 'any' = │
│ completed/failed/cancell │
│ ed. [default: any] │
│ --dry-run Preview what would │
│ change without applying │
│ it. │
│ --force -f Skip the confirmation │
│ prompt (and authorize │
│ the op when │
│ non-interactive). │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman capture 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). The Explorer 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 Explorer
ribbon'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|winr Show only items of this │
│ t] 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.
┌─ 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). │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. 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, preset.
┌─ 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. │
│ preset Apply a control preset by name, or list available presets. │
└─────────────────────────────────────────────────────────────────────────────┘
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 Set output volume 0–100 │
│ [0<=x<=100] (omit to read the │
│ current state). │
│ --mute/--unmute Mute or unmute audio │
│ output. │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman control display
Usage: pinman control display [OPTIONS]
Get or set the display.
No options reads brightness + ON/OFF; ``--brightness N`` sets the level;
``--on`` / ``--off`` / ``--toggle`` controls the blank (only one at a time).
A down overlay server fails a set (exit 1) but reports ``unavailable`` on a
read.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --brightness INTEGER RANGE Set display brightness │
│ [0<=x<=100] 0–100 (omit to read the │
│ current state). │
│ --on Turn the display ON │
│ (unblank). │
│ --off Turn the display OFF │
│ (blank). │
│ --toggle Toggle the display │
│ ON/OFF. │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman control 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|scrolli How the message is │
│ ng] displayed. [default: │
│ static] │
│ --color TEXT Message color (hex). │
│ [default: #ffffff] │
│ --duration INTEGER Auto-clear after N │
│ seconds (omit = sticky). │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. 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 preset
Usage: pinman control preset [OPTIONS] [NAME]
Apply a control preset by name, or list available presets.
Bare ``control preset`` lists presets (marking the active one); ``control
preset <name>`` applies it.
┌─ 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). A down overlay server fails a set (exit 1) but reports
``unavailable`` on a read.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --on Start the slideshow. │
│ --off Stop the slideshow. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. 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. │
└─────────────────────────────────────────────────────────────────────────────┘
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 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|ot Device class. │
│ her] [required] │
│ --vid-pid TEXT USB VID:PID (e.g. │
│ 1209:BADA). │
│ --serial TEXT Serial number. │
│ --edid TEXT Display MonitorDeviceID │
│ (required for display │
│ re-match on plug-in). │
│ --edid-serial TEXT Per-unit EDID serial │
│ (0xFF descriptor). │
│ --description TEXT Device description. │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default │
│ quiet — PINMAN_VERBOSE │
│ env var sets the │
│ default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device assign
Usage: pinman device assign [OPTIONS] DEVICE_NAME
Assign a device to a box and/or set logical device role(s).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * DEVICE_NAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --box TEXT Box name to assign to. │
│ --role TEXT Logical device role (can repeat). │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device binding
Usage: pinman device binding [OPTIONS] COMMAND [ARGS]...
Manage logical device bindings (role variables).
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ clear Remove a binding by key. │
│ list List all active bindings (auto-generated and manual). │
│ set Create or update a manual binding. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device binding clear
Usage: pinman device binding clear [OPTIONS] KEY
Remove a binding by key.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * KEY TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device binding list
Usage: pinman device binding list [OPTIONS]
List all active bindings (auto-generated and manual).
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device binding set
Usage: pinman device binding set [OPTIONS] KEY VALUE
Create or update a manual binding.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * KEY TEXT [required] │
│ * VALUE TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --description TEXT Binding description. │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device detect
Usage: pinman device detect [OPTIONS]
Scan hardware and update the device table.
Detects displays and audio devices (via WinRT) and USB HID devices (via
pywinusb), reconciling them against the device table.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --changes Only show new and gone │
│ devices. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device ghosts
Usage: pinman device ghosts [OPTIONS]
Show USB devices that are known but no longer present (unplugged).
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device list
Usage: pinman device list [OPTIONS]
List known devices.
Reads the DB — the source of truth, which may have drifted from the live
hardware. Pass --refresh to rescan hardware (a quiet detect) first.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --class [display|audio|usb|othe Filter by device class. │
│ r] │
│ --detected/--all Filter by detection │
│ status. │
│ --refresh Rescan live hardware │
│ before listing │
│ (persisted). Default │
│ reads the DB (cached). │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device remove
Usage: pinman device remove [OPTIONS] NAME
Remove a device by name or ID.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force -f Skip the confirmation prompt (and authorize the │
│ op when non-interactive). │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman device 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] DEVICE_NAME SOFTWARE_ID
Link a software catalog entry to a device.
DEVICE_NAME is the device name or numeric ID; SOFTWARE_ID is the catalog
entry ID (e.g. 'nvidia_app').
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * DEVICE_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] DEVICE_NAME
List class-default and instance software for a device.
The full catalog is available via `pinman software list`.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * DEVICE_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] DEVICE_NAME SOFTWARE_ID
Remove a software link from a device.
DEVICE_NAME is the device name or numeric ID; SOFTWARE_ID is the catalog
entry ID.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * DEVICE_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] DEVICE_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 ─────────────────────────────────────────────────────────────────┐
│ * DEVICE_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 Explorer 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"). │
└─────────────────────────────────────────────────────────────────────────────┘
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 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).
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture by │
│ ID (default: the head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --realm TEXT Filter by realm (fs, winreg, │
│ winrt, bundle). 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 show
Usage: pinman explore show [OPTIONS] LOCATION
Inspect one item by location (the Explorer detail drawer).
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 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 by ID. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ 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] ENTRY_ID
Delete a journal entry by ID.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * ENTRY_ID INTEGER [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 journal edit
Usage: pinman journal edit [OPTIONS] ENTRY_ID
Edit a journal entry's title, note, or tags.
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 ─────────────────────────────────────────────────────────────────┐
│ * ENTRY_ID INTEGER [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --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| Filter by entry source. │
│ import] │
│ --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 share
Usage: pinman journal share [OPTIONS] [ENTRY_IDS]...
Export journal entries as a markdown report.
Pass one or more entry IDs to export exactly those (selection scope), which
ignores the filters. Otherwise the current filters apply (`--source`,
`--search`, `--from`/`--to`); with none set, the entire journal is exported.
Markdown goes to stdout (pipeable) by default, or to `--file` as UTF-8.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ ENTRY_IDS INTEGER │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --source TEXT Filter by entry source. │
│ --search TEXT Text search in title / note. │
│ --from TEXT Start date (YYYY-MM-DD). │
│ --to TEXT End date (YYYY-MM-DD). │
│ --file FILE Write the payload to this file as UTF-8 │
│ (default: stdout). │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman journal show
Usage: pinman journal show [OPTIONS] [ID]
Show one journal entry's detail.
Select by positional ID or `--latest` (the newest entry).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET [ID] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest Select the newest item │
│ (mutually exclusive with a │
│ positional ID/NAME). │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman kit
Usage: pinman kit [OPTIONS] COMMAND [ARGS]...
Manage content kits (author, install, import into a project).
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ 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).
┌─ 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|warn Show only lines at this │
│ ing|error|critical] 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.
┌─ 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 power reboot
Usage: pinman power reboot [OPTIONS]
Reboot this machine.
┌─ 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 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. │
└─────────────────────────────────────────────────────────────────────────────┘
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 `readonly_mode` 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 readonly_mode 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 authoring
Usage: pinman profile authoring [OPTIONS] COMMAND [ARGS]...
Author profile scripts: scaffold · check · lint.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Authoring ─────────────────────────────────────────────────────────────────┐
│ scaffold Generate a profile script scaffold. │
│ check Dry-run a profile script: load, resolve targets, display. │
│ lint Validate a profile script's structure (exit 1 on errors). │
└─────────────────────────────────────────────────────────────────────────────┘
pinman profile authoring check
Usage: pinman profile authoring check [OPTIONS] PATH
Dry-run a profile script: load, resolve targets, display.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATH PATH [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 authoring lint
Usage: pinman profile authoring lint [OPTIONS] PATH
Validate a profile script's structure (exit 1 on errors).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATH PATH [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 authoring scaffold
Usage: pinman profile authoring scaffold [OPTIONS] NAME
Generate a profile script scaffold.
Writes to `<profiles-dir>/<slug>.py` by default; `--file PATH` overrides the
destination. `--force` overwrites an existing file without prompting.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --file FILE Write the payload to this file as UTF-8 │
│ (default: stdout). │
│ --force -f Skip the confirmation prompt (and authorize │
│ the op when non-interactive). │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman profile collect
Usage: pinman profile collect [OPTIONS] NAME
Generate a 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.
┌─ 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 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 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
Add a target 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] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --location TEXT Target location (e.g. │
│ fs:/path/file.ini#Sec/Key). │
│ [required] │
│ * --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.
┌─ 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).
┌─ 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).
┌─ 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 \
--scope '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 │
│ --scope 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 │
│ --scope 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|schedu [required] │
│ ler} │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman service start
Usage: pinman service start [OPTIONS] [[api|overlay|audio|inputs]]
Start Pinman, or one service by NAME.
With no NAME this starts the tray, which brings up every service it
supervises. With a NAME it asks the *running* tray to start that one service.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME [[api|overlay|audio|inputs]] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ 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 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 (or numeric ID). │
│ detect Detect installed pinball software on the system. │
│ launch Launch an external software/tool from the catalog by name (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] IDENT
Launch an external software/tool from the catalog by name (or numeric ID).
IDENT is the catalog name (e.g. 'VisualPinball' or a 'group:member' 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 ─────────────────────────────────────────────────────────────────┐
│ * IDENT 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 gone entries.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --all Include not-installed │
│ entries. │
│ --class [emulator|frontend|driv Filter by program class. │
│ er|tool|runtime] │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. 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] IDENT
Show detail for one catalog program by name (or numeric ID).
IDENT is the catalog name (e.g. 'VisualPinball' or a 'group:member' id).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * IDENT 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: 300] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. 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). │
│ restart Re-seed a tutorial-backed project to its baseline (start over). │
│ stage Jump a tutorial-backed project to a baked STAGE. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Commands ──────────────────────────────────────────────────────────────────┐
│ package Build tutorial TUTORIAL_ID into a distributable │
│ <id>-tutorial-<version>.zip. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial bake
Usage: pinman tutorial bake [OPTIONS] TUTORIAL_ID
(Authoring) Bake a tutorial's stage snapshots from its authoring edit
scripts.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * TUTORIAL_ID 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 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 the *active*
project offers to stop the tray and its services first (they hold the home
open).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * TUTORIAL_ARG TUTORIAL [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --name TEXT Target project name (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_ID
Build tutorial TUTORIAL_ID into a distributable <id>-tutorial-<version>.zip.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * TUTORIAL_ID 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 restart
Usage: pinman tutorial restart [OPTIONS] [NAME]
Re-seed a tutorial-backed project to its baseline (start over).
NAME is the project (default: the active project). Tutorials are disposable,
so this re-seeds frictionlessly. Re-seeding the active project offers to stop
the tray and its services first (they hold the home open).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ NAME TEXT │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ 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 tutorial stage
Usage: pinman tutorial stage [OPTIONS] NAME STAGE
Jump a tutorial-backed project to a baked STAGE.
NAME is the project; STAGE is a stage declared by its origin tutorial. The
baseline seed runs first, then the baked stage tree overlays it (the skipped
edits appear as pending drift). Re-seeding the active project offers to stop
the tray and its services first (they hold the home open).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
│ * STAGE 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 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|candi Filter by scope. │
│ date|all] Default: universal (for │
│ distribution). │
│ --file FILE Write the payload to │
│ this file as UTF-8 │
│ (default: stdout). │
│ --output -o [human|json] Output format (human | │
│ json). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist list
Usage: pinman winreg blacklist list [OPTIONS]
List all blacklist key and value patterns.
Examples:
pinman winreg blacklist list
pinman winreg blacklist list -o json
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist optimize
Usage: pinman winreg blacklist optimize [OPTIONS]
Remove redundant patterns covered by a broader wildcard.
A pattern is redundant if a broader wildcard already covers it (e.g. with
'Software\Microsoft\*' present, 'Software\Microsoft\Windows\*' is redundant).
Use --dry-run to preview; otherwise the removal is applied (force-gated).
Examples:
pinman winreg blacklist optimize --dry-run # preview redundant
pinman winreg blacklist optimize # remove (prompts)
pinman winreg blacklist optimize --force # remove (scripted)
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --blacklist-file PATH Path to blacklist file. Default: │
│ reference/winreg_blacklist.json[c]. │
│ --dry-run Preview what would change without │
│ applying it. │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist remove
Usage: pinman winreg blacklist remove [OPTIONS] PATTERN
Remove a pattern from the global blacklist.
PATTERN: the exact pattern to remove.
Examples:
pinman winreg blacklist remove "*Cache*"
pinman winreg blacklist remove "*Timestamp*" --type value
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type [key|value] Pattern type (key or value). │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist test
Usage: pinman winreg blacklist test [OPTIONS] PATTERN
Test what a pattern matches against cached extraction data.
Shows how many keys/values a pattern would match, with sample matches.
Requires cached extraction data — run 'pinman winreg extract --no-filter'
first if none exists.
Examples:
pinman winreg blacklist test "*\Classes\CLSID\*"
pinman winreg blacklist test "*LastChecked*" --type value
pinman winreg blacklist test "*\SolidWorks\*" --hive HKCU
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type [key|value] Pattern type (key or value). │
│ --hive [HKCU|HKLM|all] Which hive(s) to test against. │
│ --limit INTEGER Max matches to display. │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg clear-cache
Usage: pinman winreg clear-cache [OPTIONS]
Delete winreg pickle sidecars in the live extract directory.
Each `.reg`/`.hiv` file in `extract/winreg/` has a `.pkl` sidecar that caches
the parsed data so subsequent reads skip the parser. This deletes those
sidecars; the next read regenerates them.
Backup directories (`backup_NNN/winreg/`) are *not* touched — those sidecars
are backed up alongside their `.reg` files.
Use when forcing a fresh parse (e.g. after editing a source `.reg` without
bumping its mtime) or reclaiming disk space.
Examples:
pinman winreg clear-cache
pinman winreg clear-cache --force
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg diff
Usage: pinman winreg diff [OPTIONS] SOURCE [TARGET]
Compare winreg data between files or against live winreg.
SOURCE: Path to first .reg file
TARGET: Path to second .reg file (or omit if using --live)
Examples:
pinman winreg diff file1.reg file2.reg
pinman winreg diff backup.reg --live
pinman winreg diff old.reg new.reg -o json
pinman winreg diff old.reg new.reg -o json --file changes.json
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * SOURCE PATH [required] │
│ TARGET PATH │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --live Compare source file against │
│ live winreg. │
│ --hive [HKCU|HKLM|HKCR|HKU] Hive to compare when using │
│ --live (auto-detected if │
│ not specified). │
│ --values-only Only show value │
│ differences, not key │
│ differences. │
│ --file FILE Write the payload to this │
│ file as UTF-8 (default: │
│ stdout). │
│ --output -o [human|json] Output format (human | │
│ json). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole run; │
│ default quiet — │
│ PINMAN_VERBOSE env var sets │
│ the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover
Usage: pinman winreg discover [OPTIONS] COMMAND [ARGS]...
Discover registry changes by comparing before/after extractions.
Default scope: HKCU\Software (where app settings live).
Use --hive and --root-key to adjust scope.
Workflow:
pinman winreg discover baseline # Before your change
<make your change — install, configure, etc.>
pinman winreg discover changes # See what changed
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Discovery ─────────────────────────────────────────────────────────────────┐
│ baseline Take a baseline extraction before making changes. │
│ changes Show what changed since the last baseline. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover baseline
Usage: pinman winreg discover baseline [OPTIONS]
Take a baseline extraction before making changes.
Overwrites any existing baseline for this hive.
Examples:
pinman winreg discover baseline
pinman winreg discover baseline --root-key "Software\JoyToKey"
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM] Hive to extract (default: HKCU). │
│ --root-key TEXT Root key within hive (default: │
│ Software). │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover changes
Usage: pinman winreg discover changes [OPTIONS]
Show what changed since the last baseline.
Examples:
pinman winreg discover changes
pinman winreg discover changes -o json
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM] Hive to compare (default: HKCU). │
│ --root-key TEXT Root key within hive (default: │
│ Software). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg extract
Usage: pinman winreg extract [OPTIONS]
Extract winreg to .reg files.
By default, extracts full subtree dumps with blacklist filtering. Use
--tracked-only to extract only schema-tracked keys (fast, <1s).
With --from-file, filters an existing .reg file instead of extracting from
the live registry. Useful for post-processing raw dumps.
Destinations:
--out DIR write the .reg file(s) to a directory (default: extract
dir)
--out-file PATH write a single .reg file (single hive / --from-file)
Modes:
(default) Full extraction: dump allowed subtrees with blacklist
filtering
--tracked-only Fast: extract only schema-tracked keys via Python API
--no-filter No filtering - extract everything (raw)
Examples:
pinman winreg extract --hive HKCU
pinman winreg extract --hive all --out ./registry_backup
pinman winreg extract --tracked-only
pinman winreg extract --hive HKLM --no-filter
pinman winreg extract --from-file raw_dump.reg --out-file filtered.reg
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM|all] Winreg hive to extract (default: │
│ HKCU). Use 'all' for HKCU and │
│ HKLM. │
│ --out DIRECTORY Output DIRECTORY for the .reg │
│ file(s) (default: the extract │
│ dir). │
│ --out-file FILE Single output .reg file (single │
│ hive / --from-file only). │
│ --root-key TEXT Root key within hive to extract │
│ (e.g., Software/MyApp). │
│ --tracked-only Extract only schema-tracked keys │
│ (fast, <1s). Requires schema │
│ context. │
│ --no-filter Raw mode: skip all blacklist │
│ filtering (extract everything). │
│ --from-file FILE Filter an existing .reg file │
│ instead of extracting from live │
│ registry. │
│ --encoding [utf-8|utf-16] Output file encoding. │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg inventory
Usage: pinman winreg inventory [OPTIONS]
List winreg: entries from the schema and check if they exist on the system.
Shows which registry keys defined in your schema are present on the system
and which are missing (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-d Keep dump files after │
│ umps watch completes (default: │
│ keep). │
│ --output -o [human|json] Output format (human | │
│ json). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole │
│ run; default quiet — │
│ PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winrt
Usage: pinman winrt [OPTIONS] COMMAND [ARGS]...
Windows Runtime (winrt:) settings commands.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ WinRT ─────────────────────────────────────────────────────────────────────┐
│ extract Extract live WinRT settings to a JSON snapshot file. │
│ diff Compare WinRT JSON files or against live settings. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winrt diff
Usage: pinman winrt diff [OPTIONS] SOURCE [TARGET]
Compare WinRT JSON files or against live settings.
SOURCE: Path to first JSON file
TARGET: Path to second JSON file (or omit if using --live)
Examples:
pinman winrt diff backup.json --live
pinman winrt diff old.json new.json
pinman winrt diff backup.json --live -o json
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * SOURCE PATH [required] │
│ TARGET PATH │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --live Compare source file against │
│ live WinRT settings. │
│ --values-only Only show property value │
│ differences. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winrt extract
Usage: pinman winrt extract [OPTIONS]
Extract live WinRT settings to a JSON snapshot file.
Writes all 14 Windows Settings categories (sound, display, gaming, GPU,
power, network, security, services, startup, about, monitoring,
personalization, accessibility, input) to a snapshot file. With ``-o
json|yaml`` the extracted data is also emitted to stdout (the file is still
written; progress goes to stderr).
Modes:
(default) Full extraction: all categories to winrt_settings.json
--tracked-only Schema-scoped: tracked paths only to
winrt_settings_tracked.json
Examples:
pinman winrt extract
pinman winrt extract -o json | jq
pinman -v winrt extract --category Services
pinman winrt extract --out my_settings.json
pinman winrt extract --tracked-only
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --out FILE Snapshot destination │
│ (default: │
│ {app_data}/extract/winrt │
│ /winrt_settings.json). │
│ --category [About|Accessibility|Di Extract only this │
│ splay|Gaming|GPU|Input| category. │
│ Monitoring|Network|Pers │
│ onalization|Power|Secur │
│ ity|Services|Sound|Star │
│ tup] │
│ --tracked-only Extract only │
│ schema-tracked │
│ properties (fast). │
│ Writes │
│ winrt_settings_tracked.j │
│ son instead of the full │
│ file. │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘