Pinman CLI Reference
Pinman 2.0.261115-c90f0b8 Beta — generated 2026-11-15
pinman auth
Usage: pinman auth [OPTIONS] COMMAND [ARGS]... Manage UI login PINs (roles.json in the project home). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ list List the login roles (PINs are never shown). │ │ reset Reset ROLE's PIN back to its factory default. │ │ set Set ROLE's PIN (operator or technician). PIN must be 4-8 digits. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman auth list
Usage: pinman auth list [OPTIONS] List the login roles (PINs are never shown). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman auth reset
Usage: pinman auth reset [OPTIONS] ROLE Reset ROLE's PIN back to its factory default. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ROLE TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman auth set
Usage: pinman auth set [OPTIONS] ROLE PIN Set ROLE's PIN (operator or technician). PIN must be 4-8 digits. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ROLE TEXT [required] │ │ * NEW_PIN PIN [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box
Usage: pinman box [OPTIONS] COMMAND [ARGS]... Manage boxes (device grouping containers). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Boxes ─────────────────────────────────────────────────────────────────────┐ │ list List all boxes. │ │ show Show box detail with devices, setup profile, and drift status. │ │ create Create a new box. │ │ rename Rename a box. │ │ delete Delete a box (devices are unassigned, not deleted). │ │ use Switch to a root box (make it the active box), deactivating the │ │ current one. │ │ set-setup Set the setup profile for a box. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Computer membership ───────────────────────────────────────────────────────┐ │ assign Add the Computer to a box: `box assign computer --box <box>`. │ │ unassign Remove the Computer from a box: `box unassign computer --box │ │ <box>`. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box assign
Usage: pinman box assign [OPTIONS] SUBJECT Add the Computer to a box: `box assign computer --box <box>`. Device↔box membership is device-side — use `pinman device assign --box`. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * SUBJECT TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --box TEXT Box name to add the Computer to. │ │ [required] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box create
Usage: pinman box create [OPTIONS] NAME
Create a new box.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --type TEXT Box type (e.g. computer, enclosure, │
│ controller). [required] │
│ --parent TEXT Parent box name (for nesting). │
│ --active Mark as active system root. │
│ --description TEXT Box description. │
│ --setup-profile TEXT Setup profile path (relative to profiles │
│ dir). │
│ --setup-inputs TEXT Setup profile inputs as JSON, e.g. │
│ '{"volume":75}'. │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman box delete
Usage: pinman box delete [OPTIONS] NAME Delete a box (devices are unassigned, not deleted). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box list
Usage: pinman box list [OPTIONS] List all boxes. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box rename
Usage: pinman box rename [OPTIONS] NAME NEW_NAME Rename a box. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ │ * NEW_NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box set-setup
Usage: pinman box set-setup [OPTIONS] NAME
Set the setup profile for a box.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --setup-profile TEXT Profile path relative to profiles dir. │
│ [required] │
│ --setup-inputs TEXT Profile inputs as JSON, e.g. │
│ '{"volume":75}'. │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │
│ logs (applies to the whole run; default │
│ quiet — PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman box show
Usage: pinman box show [OPTIONS] [NAME] Show box detail with devices, setup profile, and drift status. If NAME is given, show that box only. Otherwise show all boxes. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box unassign
Usage: pinman box unassign [OPTIONS] SUBJECT Remove the Computer from a box: `box unassign computer --box <box>`. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * SUBJECT TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --box TEXT Box name to remove the Computer from. │ │ [required] │ │ --force -f Skip the confirmation prompt (and │ │ authorize the op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman box use
Usage: pinman box use [OPTIONS] NAME Switch to a root box (make it the active box), deactivating the current one. If the box has a setup profile configured, shows its drift status and offers to apply it, then runs `profile apply`'s display countdown and guided actions. `--force` applies without prompting or the countdown; `--no-apply` skips it. Under `machine_readonly` the setup-profile apply is previewed; pass `--allow-writes` to authorize this one invocation to write. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --no-apply Switch only; skip the setup-profile apply prompt. │ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --allow-writes Write to the machine even though machine_readonly │ │ is enabled. │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture
Usage: pinman capture [OPTIONS] COMMAND [ARGS]... Manage system state captures (checkpoints, savepoints, and their backups). Maintenance verbs (repair-head, unlock, clean, workers) live under `pinman capture maint`. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ broaden Broaden a capture — widen its floor and materialize to it, in │ │ place. │ │ capacity Report free space vs. estimated savepoint size on backups_root. │ │ chain Show a capture's history chain (newest -> oldest). │ │ changes Show a capture's changes vs its baseline (read-only; creates │ │ nothing). │ │ check Check a capture's record and item rows for internal │ │ contradictions. │ │ cleanup Bulk-delete captures matching filters (chain-safe). │ │ coverage Show a capture's coverage: its base floor plus every │ │ per-container extension. │ │ create Freeze the head into a new capture (the kind is derived from the │ │ levers). │ │ delete Delete a capture (chain-safe). │ │ dump Dump a capture's items tree as JSON/YAML. │ │ list List existing captures. │ │ maint Capture maintenance: repair the head, clear the lock, prune │ │ incompletes, tune workers. │ │ move Move/relocate backed up captures and update database references. │ │ refresh Refresh the head — re-read live values for its existing coverage. │ │ restore Restore LOCATIONS as capture CAPTURE_ID recorded them; its files │ │ when none are named. │ │ show Show a capture with its hierarchical items tree. │ │ verify Verify the stored bytes of a backed up capture. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture broaden
Usage: pinman capture broaden [OPTIONS] [ID]
Broaden a capture — widen its floor and materialize to it, in place.
Defaults to the head; select a frozen capture by positional ID or `--latest`
(the newest backup), which may broaden granularity from its stored bytes.
Relax-only: each lever may stay or widen (--scope discovery widens tracked →
discovery; --granularity settings widens file → settings); narrowing or a
no-op is an error. The floor (`scan_props_json`) is rewritten and the kind
label re-derives (e.g. File Checkpoint → Checkpoint). The granularity axis
reads held data (the head's extract, or a frozen backup capture's stored
bytes); the scope axis re-extracts the newly-in-scope breadth (head only —
frozen captures never read live). CLI counterpart of the Explore toolbar's
Broaden (API `POST /captures/{id}/broaden`); run synchronously here.
With --item LOCATION, broadens ONE container instead (API `POST
/captures/{id}/items/{iid}/broaden`): the scope axis is a surgical live read
of that container's immediate children (winreg subtrees above the size gate
run regardless here — the CLI is the confirmed path); on a frozen capture
only backed up real-file rows can serve scope from stored bytes. The capture
floor and kind label are untouched.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ TARGET [ID] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --latest Select the newest item (mutually │
│ exclusive with a positional │
│ ID/NAME). │
│ --item TEXT Broaden ONE container: the item │
│ location (e.g. 'fs:/c:/MyApp/...', │
│ 'winreg:/HKEY_CURRENT_USER/...'), │
│ resolved as the capture sees it — │
│ a row shared from an ancestor │
│ capture is addressable. Requires │
│ an axis flag. The capture │
│ floor/kind are untouched │
│ (container broaden is view-extent │
│ coverage). │
│ --scope [discovery] Widen scope: tracked → discovery │
│ (head only) │
│ --granularity [settings] Widen granularity: file → settings │
│ --include-hidden With --item: also list the │
│ container's untracked hidden and │
│ temporary entries (head only; │
│ until the next capture). Implies │
│ --scope discovery where needed. │
│ --no-winreg-extract Skip winreg extraction │
│ (whole-capture scope axis; use │
│ when already extracted) │
│ --no-winrt-extract Skip winrt extraction │
│ (whole-capture scope axis; use │
│ when already extracted) │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman capture capacity
Usage: pinman capture capacity [OPTIONS] Report free space vs. estimated savepoint size on backups_root. Default: estimates a full savepoint (all tracked fs files + winreg/winrt extracts). With --for-next-backup, estimates only the delta vs. the last completed savepoint. Classifies as ``ok``, ``low``, or ``not_enough`` against ``backup_capacity_low_multiplier`` (default 3x). Exit codes for scripting: 0 = ok, 1 = low, 2 = not_enough. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --for-next-backup Estimate space for the next │ │ incremental savepoint (files │ │ modified since the last completed │ │ savepoint). Falls back to a full │ │ estimate when no prior savepoint │ │ exists. Used by the savepoint │ │ pre-flight check. │ │ --force-estimate Use the heuristic for extract sizes │ │ even if real extract files exist. │ │ --output -o [human|json] Output format (human | json). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. │ │ progress logs (applies to the whole │ │ run; default quiet — PINMAN_VERBOSE │ │ env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture chain
Usage: pinman capture chain [OPTIONS] [ID] Show a capture's history chain (newest -> oldest). Select by positional ID or `--latest` (the newest backup capture). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture changes
Usage: pinman capture changes [OPTIONS] [ID] Show a capture's changes vs its baseline (read-only; creates nothing). Folds the source capture's already-materialized rows against the reference — a pure read, no scan and no row created. Defaults to the head; select a stored capture by positional ID, or `--latest` for the newest non-head one. Omit `--reference` to diff against the source's own baseline; an explicit `--reference <id>` must be older than the source; `--no-reference` shows changes vs a bare baseline. Run `pinman capture refresh` first if you want the head's rows brought current before reading them. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with │ │ a positional ID/NAME). │ │ --reference TEXT Reference capture ID │ │ (must be older than the │ │ source). Omit to diff │ │ against the source's own │ │ baseline reference. │ │ --no-reference Do not use any reference │ │ capture. │ │ --compact/--no-compact Show each run of │ │ path-only folders above a │ │ tracked item as one row. │ │ [default: compact] │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole │ │ run; default quiet — │ │ PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture check
Usage: pinman capture check [OPTIONS] [ID] Check a capture's record and item rows for internal contradictions. Defaults to the head. Select another by positional ID or `--latest`; use `--every-capture` for all of them (`--all` means the other axis on `capture verify`, so it is deliberately not spelled that way). Findings are hidden or shown by `persistence` and counted by `severity`, and the two are never crossed: a self-healing finding stays out of the default printout and still fails the run. Exit codes: 0 clean, 1 at or above `--fail-on`, 2 usage. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --every-capture Widen the tree checks to every │ │ capture, not just the head. │ │ Never verifies bytes. │ │ --stale Print the self-healing │ │ findings the default only │ │ counts (display only). │ │ --observe Print the tier C observations. │ │ --fail-on [error|warn] Exit 1 on any finding at or │ │ above this severity. [default: │ │ error] │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture cleanup
Usage: pinman capture cleanup [OPTIONS] Bulk-delete captures matching filters (chain-safe). Each matching capture is removed via `capture_delete` (oldest-first, so backed-up bytes merge cleanly into each successor). The head is never a candidate, nor are pending/in-progress captures. Default `--backup false` operates only on compares / checkpoints and never touches backups or savepoints (resume targets); pass `--backup true` to reclaim disk from old backups. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --source TEXT Filter by source: 'head' │ │ (unfrozen, no source — │ │ not completed backups, │ │ which carry a freeze │ │ stamp), a capture ID, or │ │ 'any'. [default: any] │ │ --reference TEXT Filter by reference │ │ capture ID, or 'any'. │ │ [default: any] │ │ --backup [true|false|any] Filter by │ │ backed-up-bytes kind: │ │ 'true' │ │ (savepoints/backups │ │ only), 'false' │ │ (non-backed up only), │ │ 'any' (no filter). │ │ [default: false] │ │ --older-than TEXT Only captures created │ │ before this age (e.g. │ │ 90d, 6mo, 1y). │ │ --status [completed|failed|cance Filter by terminal │ │ lled|any] status. 'any' = │ │ completed/failed/cancell │ │ ed. [default: any] │ │ --dry-run Preview what would │ │ change without applying │ │ it. │ │ --force -f Skip the confirmation │ │ prompt (and authorize │ │ the op when │ │ non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture coverage
Usage: pinman capture coverage [OPTIONS] [ID] Show a capture's coverage: its base floor plus every per-container extension. Defaults to the working capture (the head, else the newest); `--latest` is the newest capture of any kind, as `capture show`. A frozen savepoint carries extensions too (`capture broaden --item` can widen one in place from its stored bytes) — reach it by ID, since freezing spawns a newer head and `--latest` would return that instead. The base floor is the whole-capture extent (`capture create` sets it, `capture broaden` widens it). An extension is one container the user asked to see more of: it widens the floor THAT container enumerates its children at, and reaches no further down. Accumulated rows are what the capture holds without promising — every Refresh re-reads them, and a new capture clears them. Counterpart of the Explorer ribbon's Coverage group. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture create
Usage: pinman capture create [OPTIONS]
Freeze the head into a new capture (the kind is derived from the levers).
Bare `capture create` makes a File Checkpoint (no copy, file-level, tracked
items only). Add `--backup` for a Savepoint, `--granularity settings` for
full per-setting detail, `--scope discovery` for a `+` kind — or use `--kind`
as a shortcut. The resulting kind is printed on success.
Examples:
pinman capture create # File Checkpoint
pinman capture create --backup # Savepoint
pinman capture create --kind "file savepoint" # File Savepoint
pinman capture create --kind savepoint --scope discovery # Savepoint+
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --backup/--no-backup Back up a restorable │
│ copy of changed bytes │
│ (Savepoint). Off = │
│ metadata-only │
│ Checkpoint. [default: │
│ no-backup] │
│ --granularity [file|settings] Granularity: 'file' │
│ (file-level only — the │
│ 'File' kinds) or │
│ 'settings' (full │
│ per-setting detail). │
│ [default: file] │
│ --scope [tracked|discovery] Scope: 'tracked' │
│ (schema-tracked items │
│ only) or 'discovery' │
│ (also find untracked │
│ items — the '+' kinds). │
│ [default: tracked] │
│ --kind TEXT Preset the levers from │
│ a kind label (e.g. │
│ 'checkpoint', │
│ 'savepoint', 'file │
│ savepoint+'). Explicit │
│ levers override the │
│ preset. │
│ --title TEXT Title for the capture. │
│ --note TEXT Journal annotation for │
│ this capture. │
│ --zone TAG Zone tag (repeatable). │
│ --software ID Software reference │
│ (repeatable). │
│ --auto-associate/--no- Associate the entry │
│ auto-associate with the Zones and │
│ Software of changed │
│ tracked items. │
│ [default: │
│ auto-associate] │
│ --resume Resume the last │
│ incomplete savepoint │
│ (only valid with │
│ --backup). │
│ --no-capacity-check Skip the pre-flight │
│ disk space check │
│ (savepoints only). │
│ --yes -y Skip the │
│ discovery-scope │
│ confirmation prompt │
│ (proceed even if │
│ large). │
│ --dry-run Preview what would │
│ change without applying │
│ it. │
│ --no-winreg-extract Skip winreg extraction │
│ (use when already │
│ extracted for a │
│ discovery workflow). │
│ --no-winrt-extract Skip winrt extraction │
│ (use when already │
│ extracted for a │
│ discovery workflow). │
│ --no-extract Skip both winreg and │
│ winrt extraction. │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default │
│ quiet — PINMAN_VERBOSE │
│ env var sets the │
│ default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman capture delete
Usage: pinman capture delete [OPTIONS] [ID] Delete a capture (chain-safe). Select by positional ID or `--latest` (the newest non-head capture). Routes through `capture_delete`, which collapses the chain into the deleted capture's immediate successor (re-points references, merges backed-up bytes). Refuses the head. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item (mutually exclusive with a │ │ positional ID/NAME). │ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture dump
Usage: pinman capture dump [OPTIONS] [ID] Dump a capture's items tree as JSON/YAML. Defaults to the working capture (the head, else the newest). Select a specific one by positional ID, or `--latest` for the newest — giving both is a usage error (no silent override). By default the tree is rendered with chain-back applied — rows reached via backup ancestors have their change_type/descendents_changes_count translated, matching what the API serves to the UI. Use --raw to dump the underlying DB rows verbatim. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --file FILE Write the payload to this file │ │ as UTF-8 (default: stdout). │ │ --raw Dump raw DB rows without │ │ chain-back translation │ │ (chain-reached rows keep their │ │ stored change_type instead of │ │ being translated to │ │ UNCHANGED). │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture list
Usage: pinman capture list [OPTIONS] List existing captures. `--backup true` narrows to captures that backed up their bytes (savepoints / backups) — the view the former `pinman backup list` provided; `--backup false` shows only non-backed up; the default `any` shows everything. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --backup [true|false|any] Filter by backed-up-bytes │ │ kind: 'true' │ │ (savepoints/backups only), │ │ 'false' (non-backed up only), │ │ 'any' (no filter). [default: │ │ any] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture maint
Usage: pinman capture maint [OPTIONS] COMMAND [ARGS]... Capture maintenance: repair the head, clear the lock, prune incompletes, tune workers. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ clean Delete incomplete (failed / interrupted) backup captures. │ │ repair-head Ensure a head exists (fail-safe). │ │ unlock Clear abandoned lock metadata; a live operation keeps its │ │ ownership. │ │ workers Show or tune the threaded backup copy worker count. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture maint clean
Usage: pinman capture maint clean [OPTIONS] Delete incomplete (failed / interrupted) backup captures. Default removes only the latest backup if it is incomplete; `--all` removes every incomplete backup. Refuses while a capture is running. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --all/--latest Delete all incomplete backup captures (default: │ │ only the latest, if incomplete). [default: │ │ latest] │ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture maint repair-head
Usage: pinman capture maint repair-head [OPTIONS] Ensure a head exists (fail-safe). If a capture exists but no head does — a backup-only history, or a head removed out-of-band — spawn a fresh head over the latest frozen capture (no scan, inheriting its levers). Explore does this automatically on load; this exposes it explicitly. No-op when a head already exists; reports when there are no captures to reference. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture maint unlock
Usage: pinman capture maint unlock [OPTIONS] Clear abandoned lock metadata; a live operation keeps its ownership. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture maint workers
Usage: pinman capture maint workers [OPTIONS] Show or tune the threaded backup copy worker count. Default (no flags): show current config value and what auto would recommend, without writing. Use ``--auto`` to probe storage and persist the recommendation; use ``--set N`` to write a literal value; use ``--no-fs-scan`` to consider only the backups_root drive. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --auto Probe storage and write the │ │ recommended value to config. │ │ --set INTEGER Write a literal value to config │ │ (skips probing). │ │ --no-fs-scan Skip the fs_root source probe; │ │ consider only the backups_root │ │ drive. │ │ --output -o [human|json] Output format (human | json). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. │ │ progress logs (applies to the whole │ │ run; default quiet — PINMAN_VERBOSE │ │ env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture move
Usage: pinman capture move [OPTIONS] Move/relocate backed up captures and update database references. Examples: # Repair mode: fix DB paths to match current config pinman capture move --repair # Move from current backups_root to new location pinman capture move --to "D:/pinman-backups" # DB-only mode: update refs after manual file move pinman capture move --from "C:/old" --to "C:/new" --db-only ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --to PATH Destination backup root directory. │ │ --from PATH Source backup root directory. [default: │ │ (current backups_root)] │ │ --repair Auto-detect and fix DB paths to match │ │ current backups_root config. │ │ --db-only Only update database (files already │ │ moved manually). │ │ --dry-run Preview what would change without │ │ applying it. │ │ --force -f Skip the confirmation prompt (and │ │ authorize the op when non-interactive). │ │ --verify/--no-verify Verify files after copy (when moving │ │ files). │ │ --keep-source Don't delete source after successful │ │ move. │ │ --no-update-config Don't update backups_root in config │ │ after success. │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture refresh
Usage: pinman capture refresh [OPTIONS]
Refresh the head — re-read live values for its existing coverage.
Lever-preserving and coverage-wide: re-scans at the head's own recorded floor
(scope and granularity unchanged — the server reads them from the capture, no
flags to get wrong), then value-refreshes coverage outside the floor
(lazy-expanded subtrees, broadened slices). Never adds or removes coverage,
never changes the floor or the kind label. UI counterpart of the Explore
toolbar's Refresh (API `POST /captures/{id}/refresh`); run synchronously
here.
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --no-winreg-extract Skip winreg extraction (use │
│ when already extracted) │
│ --no-winrt-extract Skip winrt extraction (use │
│ when already extracted) │
│ --output -o [human|json|yaml] Output format (human | json │
│ | yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env │
│ var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman capture restore
Usage: pinman capture restore [OPTIONS] CAPTURE_ID [LOCATIONS]... Restore LOCATIONS as capture CAPTURE_ID recorded them; its files when none are named. A file is replaced only when a Savepoint holds it as it is now, so the restore can be undone by restoring that Savepoint. `--take-savepoint` takes one first; `--overwrite-unsaved` replaces them anyway. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * CAPTURE_ID INTEGER [required] │ │ LOCATIONS TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --preview Show what would change; │ │ write nothing. │ │ --take-savepoint Take a Savepoint first, so │ │ what this changes can be put │ │ back. │ │ --overwrite-unsaved Change files even when no │ │ Savepoint holds them as they │ │ are now. │ │ --registry Whole capture: restore its │ │ registry too. │ │ --windows-settings Whole capture: restore its │ │ Windows settings too. │ │ --allow-writes Write to the machine even │ │ though machine_readonly is │ │ enabled. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture show
Usage: pinman capture show [OPTIONS] [ID] Show a capture with its hierarchical items tree. Defaults to the working capture (the head, else the newest). Select a specific one by positional ID, or `--latest` for the newest. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest │ │ item (mutually │ │ exclusive with a │ │ positional ID/NAME). │ │ --all Show all items │ │ --changes Show changed items │ │ and unresolved │ │ read/comparison gaps │ │ (default) │ │ --tracked Only tracked items │ │ --only [files|data|winreg|wi Show only items of │ │ nrt] this category │ │ --zones TEXT Filter by zones │ │ (comma-separated) │ │ --search TEXT Search in │ │ selector/location │ │ text │ │ --limit INTEGER Max items to display │ │ --page/--no-page Enable paging │ │ --compact/--no-compact Show each run of │ │ path-only folders │ │ above a tracked item │ │ as one row. [default: │ │ compact] │ │ --output -o [human|json|yaml] Output format (human │ │ | json | yaml). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default │ │ quiet — │ │ PINMAN_VERBOSE env │ │ var sets the │ │ default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman capture verify
Usage: pinman capture verify [OPTIONS] [ID] Verify the stored bytes of a backed up capture. Select by positional ID or `--latest` (the newest backup capture). Exits non-zero (1) when verification finds issues. For the capture's *record* rather than its bytes, see `pinman capture check`. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --all/--any Verify all items (don't stop │ │ at the first error). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config
Usage: pinman config [OPTIONS] COMMAND [ARGS]... Manage pinman app configuration settings. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Settings ──────────────────────────────────────────────────────────────────┐ │ list List all configuration settings, by group. │ │ get Get a specific configuration value. │ │ set Set a configuration value. │ │ env Show the current environment, config files, and database location. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ show Show one setting: its value, default, type and description. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config env
Usage: pinman config env [OPTIONS] Show the current environment, config files, and database location. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config get
Usage: pinman config get [OPTIONS] KEY Get a specific configuration value. Unknown keys raise (exit 1) with the list of valid keys. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * KEY TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config list
Usage: pinman config list [OPTIONS] List all configuration settings, by group. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config set
Usage: pinman config set [OPTIONS] KEY VALUE Set a configuration value. ``set_config`` validates the key (unknown → exit 1) and coerces/validates the value per key (bad value → exit 1); it never silently accepts bad input. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * KEY TEXT [required] │ │ * VALUE TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman config show
Usage: pinman config show [OPTIONS] KEY Show one setting: its value, default, type and description. Unknown keys raise (exit 1) with the list of valid keys. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * KEY TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control
Usage: pinman control [OPTIONS] COMMAND [ARGS]... Machine controls: display, audio, slideshow, inputs, message, mode. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Controls ──────────────────────────────────────────────────────────────────┐ │ show Show current machine control settings (volume, brightness, │ │ message, …). │ │ display Get or set the display. │ │ audio Get or set machine audio. │ │ slideshow Get or set the attract-mode slideshow. │ │ inputs Get or set the inputs lock (lock out the machine's physical │ │ controls). │ │ message Post, clear, or show the on-screen message. │ │ mode Switch the machine mode, or list the modes this machine offers. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control audio
Usage: pinman control audio [OPTIONS] Get or set machine audio. No options reads the current volume/mute; ``--volume N`` sets the level; ``--mute`` / ``--unmute`` sets mute. A set writes the operator kit's tracked ``rest:/audio`` items, as the Controls page does, and exits 1 on any refusal; a down audio server reports ``unavailable`` on a read. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --volume INTEGER RANGE Set output volume 0–100 │ │ [0<=x<=100] (omit to read the │ │ current state). │ │ --mute/--unmute Mute or unmute audio │ │ output. │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control display
Usage: pinman control display [OPTIONS] Get or set the display. No options reads brightness + ON/OFF; ``--brightness N`` sets the level; ``--on`` / ``--off`` / ``--toggle`` controls the blank (only one at a time). A down overlay server fails a set (exit 1) but reports ``unavailable`` on a read. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --brightness INTEGER RANGE Set display brightness │ │ [0<=x<=100] 0–100 (omit to read the │ │ current state). │ │ --on Turn the display ON │ │ (unblank). │ │ --off Turn the display OFF │ │ (blank). │ │ --toggle Toggle the display │ │ ON/OFF. │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control inputs
Usage: pinman control inputs [OPTIONS] Get or set the inputs lock (lock out the machine's physical controls). No option reads the current lock state; ``--lock`` / ``--unlock`` sets it. A down inputs server fails a set (exit 1) but reports ``unavailable`` on a read. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --lock/--unlock Lock or unlock the machine's │ │ physical inputs. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control message
Usage: pinman control message [OPTIONS] [TEXT] Post, clear, or show the on-screen message. ``control message "<text>"`` posts; ``control message --clear`` stops it; bare ``control message`` shows the current message status. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TEXT TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --clear Stop / clear the current │ │ display message. │ │ --mode [static|marquee|scrolli How the message is │ │ ng] displayed. [default: │ │ static] │ │ --color TEXT Message color (hex). │ │ [default: #ffffff] │ │ --duration INTEGER Auto-clear after N │ │ seconds (omit or 0 = │ │ continuous). │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control mode
Usage: pinman control mode [OPTIONS] [NAME] Switch the machine mode, or list the modes this machine offers. Bare ``control mode`` lists them and marks the active one; ``control mode <name>`` switches. A mode spans many settings at once, so it applies the profile — which records history and an undo point, unlike the single-setting commands above. The active mode is the one whose settings all match, and there may be none: changing any single setting leaves the machine in no mode at all. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control show
Usage: pinman control show [OPTIONS] Show current machine control settings (volume, brightness, message, …). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman control slideshow
Usage: pinman control slideshow [OPTIONS] Get or set the attract-mode slideshow. No options reads the current state; ``--on`` starts it, ``--off`` stops it (only one at a time). ``--interruptable`` makes it dismissable by touching the machine. A down overlay server fails a set (exit 1) but reports ``unavailable`` on a read. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --on Start the slideshow. │ │ --off Stop the slideshow. │ │ --interruptable With --on: any key, click or │ │ gamepad event dismisses it │ │ (attract mode). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db
Usage: pinman db [OPTIONS] COMMAND [ARGS]... Database-related commands. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inspect ───────────────────────────────────────────────────────────────────┐ │ show Show the current project and DB URL. │ │ inspect Inspect the database and show the tables with row counts. │ │ current Show current Alembic revision. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Manage ────────────────────────────────────────────────────────────────────┐ │ create Create database and tables (no migrations). │ │ reset Delete all data from the database without dropping the file. │ │ compact Compact the database file (full VACUUM), reclaiming free space to │ │ disk. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ upgrade Bring project databases up to this build's schema. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db compact
Usage: pinman db compact [OPTIONS] Compact the database file (full VACUUM), reclaiming free space to disk. Rarely needed: deletes already return space automatically via incremental auto-vacuum. This is the manual deep-compact lever — it takes a brief database-wide lock and needs free disk roughly equal to the current file size while it rebuilds. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db create
Usage: pinman db create [OPTIONS] Create database and tables (no migrations). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db current
Usage: pinman db current [OPTIONS] Show current Alembic revision. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db inspect
Usage: pinman db inspect [OPTIONS] Inspect the database and show the tables with row counts. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db reset
Usage: pinman db reset [OPTIONS] Delete all data from the database without dropping the file. Destructive: confirms in a terminal, refuses non-interactively without ``--force`` (exit 2). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db show
Usage: pinman db show [OPTIONS] Show the current project and DB URL. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman db upgrade
Usage: pinman db upgrade [OPTIONS] Bring project databases up to this build's schema. Run after installing a newer Pinman: the installer does this for you, but a hub restored from backup, copied between machines, or left behind by a manual file swap needs it run by hand. Stops Pinman for the duration — migrating a SQLite database under a live API (and its scheduler) risks lock errors, and the pre-upgrade copy would be taken while something else is still writing. Idempotent — a project already at head is reported and skipped. Each database that IS migrated is copied to ``pinman.db.pre-<revision>`` first; there are no backwards migrations, so that copy is the way back. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --all-projects/--active- Migrate every project │ │ only in the hub (default), │ │ or only the active one. │ │ --force -f Skip the confirmation │ │ prompt (and authorize │ │ the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default │ │ quiet — PINMAN_VERBOSE │ │ env var sets the │ │ default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device
Usage: pinman device [OPTIONS] COMMAND [ARGS]... Manage devices: detection, inventory, assignment, bindings, software. Role definitions live under `pinman device role`; assignments use `pinman device assign --role`. Bindings and software links have their own nested groups. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Detection ─────────────────────────────────────────────────────────────────┐ │ detect Scan hardware and update the device table. │ │ ghosts Show USB devices that are known but no longer present (unplugged). │ │ status Check status of the active box's devices (presence, health, ports). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inventory ─────────────────────────────────────────────────────────────────┐ │ list List known devices. │ │ show Show detail for a single device by name or ID. │ │ add Manually add a device (for non-auto-detected hardware). │ │ remove Remove a device by name or ID. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Assignment ────────────────────────────────────────────────────────────────┐ │ assign Assign a device to a box and/or set logical device role(s). │ │ unassign Unassign a device: remove from one box, or clear box/roles/both. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Sub-groups ────────────────────────────────────────────────────────────────┐ │ binding Manage logical device bindings (role variables). │ │ software Manage software-catalog links for a device. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ role Manage schema-defined logical device roles. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device add
Usage: pinman device add [OPTIONS] NAME Manually add a device (for non-auto-detected hardware). Pre-declared displays should carry --edid so detection matches them on plug-in (flips detected=True) instead of creating a duplicate record. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --class [display|audio|usb|ot Device class. │ │ her] [required] │ │ --vid-pid TEXT USB VID:PID (e.g. │ │ 1209:BADA). │ │ --serial TEXT Serial number. │ │ --edid TEXT Display MonitorDeviceID │ │ (required for display │ │ re-match on plug-in). │ │ --edid-serial TEXT Per-unit EDID serial │ │ (0xFF descriptor). │ │ --description TEXT Device description. │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default │ │ quiet — PINMAN_VERBOSE │ │ env var sets the │ │ default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device assign
Usage: pinman device assign [OPTIONS] NAME Assign a device to a box and/or set logical device role(s). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --box TEXT Box name to assign to. │ │ --role TEXT Logical device role (can repeat). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device binding
Usage: pinman device binding [OPTIONS] COMMAND [ARGS]... Manage logical device bindings (role variables). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ clear Remove a binding by key. │ │ list List all active bindings (auto-generated and manual). │ │ set Create or update a manual binding. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device binding clear
Usage: pinman device binding clear [OPTIONS] KEY Remove a binding by key. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * KEY TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device binding list
Usage: pinman device binding list [OPTIONS] List all active bindings (auto-generated and manual). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device binding set
Usage: pinman device binding set [OPTIONS] KEY VALUE Create or update a manual binding. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * KEY TEXT [required] │ │ * VALUE TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --description TEXT Binding description. │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device detect
Usage: pinman device detect [OPTIONS] Scan hardware and update the device table. Detects displays and audio devices (via WinRT) and USB HID devices (via pywinusb), reconciling them against the device table. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --changes Only show new and gone │ │ devices. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device ghosts
Usage: pinman device ghosts [OPTIONS] Show USB devices that are known but no longer present (unplugged). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device list
Usage: pinman device list [OPTIONS] List known devices. Reads the DB — the source of truth, which may have drifted from the live hardware. Pass --refresh to rescan hardware (a quiet detect) first. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --class [display|audio|usb|othe Filter by device class. │ │ r] │ │ --detected/--all Filter by detection │ │ status. │ │ --refresh Rescan live hardware │ │ before listing │ │ (persisted). Default │ │ reads the DB (cached). │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device remove
Usage: pinman device remove [OPTIONS] NAME Remove a device by name or ID. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role
Usage: pinman device role [OPTIONS] COMMAND [ARGS]... Manage schema-defined logical device roles. These commands author role definitions. Use `device assign --role` to associate a detected device with one of them. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ create Create a validated logical role definition. │ │ delete Delete a role and clean its assignments and role-prefixed bindings. │ │ edit Edit role fields without changing assignments or bindings. │ │ import Import a top-level `device_roles:` list from YAML. │ │ list List role definitions (not physical-device assignments). │ │ show Show one role definition and its authored zones. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role create
Usage: pinman device role create [OPTIONS] NAME Create a validated logical role definition. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --device-class TEXT Hardware class, such as │ │ display or audio. │ │ [required] │ │ --zone TEXT Defined Zone tag │ │ (repeatable). │ │ --label TEXT Human-readable role label. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role delete
Usage: pinman device role delete [OPTIONS] NAME Delete a role and clean its assignments and role-prefixed bindings. Dry-run reports those impacts. A real deletion requires confirmation or `--force` and removes only the role references, not devices or Zone tags. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role edit
Usage: pinman device role edit [OPTIONS] NAME Edit role fields without changing assignments or bindings. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --device-class TEXT Replace the hardware class. │ │ --zone TEXT Replace zones (repeatable). │ │ --clear-zones Remove all zones from the │ │ definition. │ │ --label TEXT Replace the human-readable │ │ label. │ │ --clear-label Remove the label. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role import
Usage: pinman device role import [OPTIONS] FILE Import a top-level `device_roles:` list from YAML. Merge is the default. `--replace` synchronizes the complete role catalog; removals require confirmation or `--force` and clean active references. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FILE FILE [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --replace Also remove definitions absent │ │ from FILE. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role list
Usage: pinman device role list [OPTIONS] List role definitions (not physical-device assignments). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device role show
Usage: pinman device role show [OPTIONS] NAME Show one role definition and its authored zones. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device show
Usage: pinman device show [OPTIONS] NAME Show detail for a single device by name or ID. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device software
Usage: pinman device software [OPTIONS] COMMAND [ARGS]... Manage software-catalog links for a device. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ add Link a software catalog entry to a device. │ │ list List class-default and instance software for a device. │ │ remove Remove a software link from a device. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device software add
Usage: pinman device software add [OPTIONS] NAME SOFTWARE_ID Link a software catalog entry to a device. NAME is the device name or numeric ID; SOFTWARE_ID is the catalog entry ID (e.g. 'nvidia_app'). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ │ * SOFTWARE_ID TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device software list
Usage: pinman device software list [OPTIONS] NAME List class-default and instance software for a device. The full catalog is available via `pinman software list`. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device software remove
Usage: pinman device software remove [OPTIONS] NAME SOFTWARE_ID Remove a software link from a device. NAME is the device name or numeric ID; SOFTWARE_ID is the catalog entry ID. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ │ * SOFTWARE_ID TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device status
Usage: pinman device status [OPTIONS] Check status of the active box's devices (presence, health, ports). With --refresh (default), re-checks the active box's devices against live hardware and persists the result, so an unplugged device is noticed. Use 'pinman device detect' for system-wide discovery of new/removed hardware. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --refresh/--no-refresh Re-check the active box's │ │ devices against live │ │ hardware first (default), │ │ or report from the DB │ │ only. │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole │ │ run; default quiet — │ │ PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman device unassign
Usage: pinman device unassign [OPTIONS] NAME Unassign a device: remove from one box, or clear box/roles/both. Examples: pinman device unassign "Dell Monitor" pinman device unassign "Dell Monitor" --box Backbox pinman device unassign "Dell Monitor" --keep-box pinman device unassign "Dell Monitor" --keep-role ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --box TEXT Remove from just this one box (other box │ │ memberships are kept). │ │ --keep-box Clear roles only (keep box membership). │ │ --keep-role Remove from box only (keep roles + │ │ bindings). │ │ --force -f Skip the confirmation prompt (and authorize │ │ the op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore
Usage: pinman explore [OPTIONS] COMMAND [ARGS]... Browse, inspect, diff, tag, and manage tracked items (the UI's Explore page). Reads the head by default; pass --id/--latest on any verb to browse a specific capture instead. The lifecycle verbs (track/untrack/edit/convert) mutate the schema (the tracked structure). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Browse ────────────────────────────────────────────────────────────────────┐ │ list Browse captured items with filters (the Explore page's item browser). │ │ show Inspect one item by location (the Explore detail drawer). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inspect ───────────────────────────────────────────────────────────────────┐ │ diff Compare two items by location within one capture (A = source, B = │ │ reference). │ │ tag Add or remove zone tags on items by location (bulk). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Tracked structure ─────────────────────────────────────────────────────────┐ │ track Track an item — create a schema item so it enters the tracked set. │ │ untrack Untrack an item — remove its schema item (it leaves the tracked │ │ set). │ │ edit Edit a tracked item's metadata (label, description, zones, │ │ software refs). │ │ convert Convert a tracked section schema to a table (the UI's "Convert to │ │ table"). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ expand Expand an item one level — materialize its direct children (the │ │ Explore tree chevron). │ │ refresh Refresh this level of the head: a container and its immediate │ │ members. │ │ set Write one item's value to the machine (the UI's inline value │ │ edit). │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore convert
Usage: pinman explore convert [OPTIONS] LOCATION
Convert a tracked section schema to a table (the UI's "Convert to table").
Structural: rewrites the saved schema's type and moves its children under a
{{KEY}} row placeholder, retaining recorded capture facts. Only valid for
ini_section / xml_section items. Create a Capture after converting to
materialize the new table's rows.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * LOCATION TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture by │
│ ID (default: the head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --key TEXT Binding key name for the │
│ table. [default: KEY] │
│ --pattern TEXT Section-match pattern for the │
│ table rows. [default: *] │
│ --force -f Skip the confirmation prompt │
│ (and authorize the op when │
│ non-interactive). │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore diff
Usage: pinman explore diff [OPTIONS] LOCATION_A LOCATION_B
Compare two items by location within one capture (A = source, B = reference).
Folds A-vs-B with the same engine the `capture changes` derive uses, so
containers show their changed subtree and leaves show a value/size delta.
Both locations are resolved in the same capture (default: the head).
Example:
pinman explore diff "fs:C:/a/config.ini" "fs:C:/b/config.ini"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * LOCATION_A TEXT [required] │
│ * LOCATION_B TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture │
│ by ID (default: the │
│ head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --limit INTEGER Max folded nodes. │
│ [default: 500] │
│ --compact/--no-compact Show each run of │
│ path-only folders above a │
│ tracked item as one row. │
│ [default: compact] │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole │
│ run; default quiet — │
│ PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore edit
Usage: pinman explore edit [OPTIONS] LOCATION Edit a tracked item's metadata (label, description, zones, software refs). Updates the schema item (the UI's edit-metadata) and its linked instances. Tag changes can propagate with --propagate. Changing a whole file's interpretation requires Refresh or a new Capture to adopt its coverage. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --id INTEGER Browse a specific capture by │ │ ID (default: the head). │ │ --latest Browse the newest capture │ │ (mutually exclusive with │ │ --id). │ │ --itemtype TEXT Change a whole file's │ │ supported interpretation. │ │ --label TEXT New label. │ │ --description TEXT New description. │ │ --schema-props JSON Replace schema rules with a │ │ JSON object. │ │ --zone TAG Replace zone tags │ │ (repeatable). │ │ --software ID Replace software refs │ │ (repeatable). │ │ --propagate [none|children|all] Propagate Zone and Software │ │ association changes to │ │ descendants. [default: none] │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore expand
Usage: pinman explore expand [OPTIONS] LOCATION
Expand an item one level — materialize its direct children (the Explore tree
chevron).
Against the head (default), children materialize at the capture floor from
live data (fs) or the head's existing extract (winreg/winrt), copying the row
up from a frozen ancestor when needed. Against a frozen capture
(--id/--latest), a stored-bytes row expands in place, snapshot-age.
A cold tracked winreg hive extracts that ONE hive's tracked keys on demand
first (what the UI's `winreg_extract` dispatch runs as a polled task) rather
than dead-ending on "run Refresh"; here it runs synchronously.
Example:
pinman explore expand "fs:/C/MyApp/settings.ini#Display"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * LOCATION TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture by │
│ ID (default: the head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore list
Usage: pinman explore list [OPTIONS]
Browse captured items with filters (the Explore page's item browser).
Source defaults to the head; use --id/--latest to browse a specific capture.
With no --changed, all items are shown (capped by --limit).
--at LOCATION re-roots the tree at one container (the API's `GET
/captures/{id}?location=...`). This is how below-floor and chain-shared rows
become visible: a head's whole-tree read is bounded to its own
granularity/scope floor, so borrowed deeper rows are dropped — re-rooting at
the container resolves the floor from the capture that owns the row instead.
Its children are listed, as the capture root's are.
Example:
pinman explore list --at "winrt:/Sound"
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture │
│ by ID (default: the │
│ head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --at LOCATION Re-root the tree at one │
│ container (the Explore │
│ page's drill-in). Reaches │
│ rows the whole-tree view │
│ bounds out at the capture │
│ floor. │
│ --realm TEXT Filter by realm (fs, │
│ winreg, winrt, bundle, │
│ rest). Repeatable. │
│ --tracked Only tracked │
│ (schema-bound) items. │
│ --changed Changed items and │
│ unresolved │
│ read/comparison gaps. │
│ --software TEXT Filter by Software entry │
│ or group ID (group prefix │
│ matches). Repeatable. │
│ --search TEXT Case-insensitive match in │
│ selector or location. │
│ --view [tree|flat|table] Human render style │
│ (machine output is always │
│ the structured tree). │
│ [default: tree] │
│ --detail [simple|advanced] Detail level (advanced │
│ shows more per item in │
│ tree view). [default: │
│ simple] │
│ --depth INTEGER Limit displayed items to │
│ this many levels deep │
│ (presentation only; all │
│ views). │
│ --compact/--no-compact Show each run of │
│ path-only folders above a │
│ tracked item as one row. │
│ [default: compact] │
│ --limit INTEGER Max items to return. │
│ [default: 500] │
│ --output -o [human|json|yaml] Output format (human | │
│ json | yaml). [default: │
│ human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole │
│ run; default quiet — │
│ PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore refresh
Usage: pinman explore refresh [OPTIONS] LOCATION Refresh this level of the head: a container and its immediate members. Deeper recorded contents retain their previous values until explicitly refreshed. Use `capture refresh` to refresh the whole head. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore set
Usage: pinman explore set [OPTIONS] LOCATION VALUE
Write one item's value to the machine (the UI's inline value edit).
Distinct from `explore edit`, which changes an item's METADATA. This changes
the setting itself, in the property's own stored units — volume is 0.0-1.0,
not 0-100.
Only a TRACKED location can be written — the schema is the gate, so a setting
Pinman merely discovered is refused until `explore track` declares it. Also
gated by `machine_readonly`; `--allow-writes` authorizes this one invocation.
With `require_savepoint` on, a file no Savepoint holds is refused:
`--take-savepoint` takes one first, `--overwrite-unsaved` writes anyway.
Exits non-zero when the write is refused.
Put `--` before a value that starts with a dash, or it is read as an option.
Option parsing stays strict on purpose: silently accepting a mistyped flag as
the value would write it to the machine.
Examples:
pinman explore set "fs:/C/MyApp/settings.ini#Display/Width" 3840
pinman explore set -- "fs:/C/MyApp/settings.ini#Display/Offset" -1
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * LOCATION TEXT [required] │
│ * VALUE TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --allow-writes Write to the machine even │
│ though machine_readonly is │
│ enabled. │
│ --take-savepoint Take a Savepoint first, so │
│ what this changes can be put │
│ back. │
│ --overwrite-unsaved Change files even when no │
│ Savepoint holds them as they │
│ are now. │
│ --output -o [human|json|yaml] Output format (human | json │
│ | yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env │
│ var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore show
Usage: pinman explore show [OPTIONS] LOCATION
Inspect one item by location (the Explore detail drawer).
Also reports which broaden axes this row can serve and at what cost — the
signal behind the Explore page's per-row lever toggles. An axis is omitted
when the floor doesn't narrow that lever at this row (nothing to widen, or a
broaden already widened it here); an unavailable one carries the reason.
Widen it with `pinman capture broaden --item LOCATION`.
Example:
pinman explore show "fs:C:/MyApp/settings.ini"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * LOCATION TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --id INTEGER Browse a specific capture by │
│ ID (default: the head). │
│ --latest Browse the newest capture │
│ (mutually exclusive with │
│ --id). │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman explore tag
Usage: pinman explore tag [OPTIONS] LOCATION... Add or remove zone tags on items by location (bulk). Applies EXISTING zone-tag definitions to tracked items — this is tag APPLICATION, distinct from `pinman tag` (which manages tag DEFINITIONS). Items must be tracked (schema-bound). Undefined tags are rejected on --add; --remove strips a tag regardless (so orphaned tags can be cleaned up). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * LOCATIONS LOCATION... [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --add TAG Zone tag to add. Repeatable. │ │ --remove TAG Zone tag to remove. │ │ Repeatable. │ │ --id INTEGER Browse a specific capture by │ │ ID (default: the head). │ │ --latest Browse the newest capture │ │ (mutually exclusive with │ │ --id). │ │ --propagate [none|children|all] Also apply the change to │ │ descendants. [default: none] │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore track
Usage: pinman explore track [OPTIONS] LOCATION Track an item — create a schema item so it enters the tracked set. Additive (the UI's Explore/Schema "Track"): creates a schema item from the item at LOCATION, backfilling untracked parent containers. Named INI sections track one setting by default; --selector requests an explicit rule. Run `pinman capture refresh` to re-materialize the tree against the new schema. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --id INTEGER Browse a specific capture by │ │ ID (default: the head). │ │ --latest Browse the newest capture │ │ (mutually exclusive with │ │ --id). │ │ --selector TEXT Target selector; use */KEY for │ │ a property template. │ │ --itemtype TEXT Interpret the target as this │ │ supported item type. │ │ --label TEXT Label for the tracked schema │ │ item. │ │ --description TEXT Description for the tracked │ │ schema item. │ │ --schema-props JSON Full schema rules as a JSON │ │ object. │ │ --zone TAG Zone tag to set (repeatable). │ │ --software ID Software reference │ │ (repeatable). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman explore untrack
Usage: pinman explore untrack [OPTIONS] LOCATION Untrack an item — remove its schema item (it leaves the tracked set). Destructive (the UI's "Untrack"): deletes the schema item and orphans its instances. Blocked if the schema has tracked children — untrack those first. After untracking, run `pinman capture refresh` to re-materialize the tree. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --id INTEGER Browse a specific capture by │ │ ID (default: the head). │ │ --latest Browse the newest capture │ │ (mutually exclusive with │ │ --id). │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman file
Usage: pinman file [OPTIONS] COMMAND [ARGS]... File formats Pinman reads and writes. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inspect ───────────────────────────────────────────────────────────────────┐ │ list File formats Pinman supports, from the live declarations. │ │ show Everything Pinman declares about one file format. │ │ check Can Pinman write this file? Runs the real writer against a copy. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman file check
Usage: pinman file check [OPTIONS] [PATH] Can Pinman write this file? Runs the real writer against a copy. Your file is never touched: its bytes are copied to a temporary directory and every write happens there. Reports two things that are not the same — what this release lets you do with the file, and what the writer does to it when measured. `--schema` checks every file your schema declares, as declared. Exit codes: 0 clean, 1 at or above `--fail-on`, 2 usage. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ PATH FILE │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --schema Check every file the active │ │ project's schema declares, │ │ instead of one file. │ │ --item SELECTOR With --schema, check only the │ │ declared item with this │ │ selector. │ │ --as FORMAT Read the file as this format. │ │ Required when its extension │ │ names several. │ │ --prop KEY=VALUE A schema property the format │ │ needs, e.g. primary_key=ID. │ │ Repeatable. │ │ --fail-on [error|warn] Exit 1 on any finding at or │ │ above this severity. [default: │ │ error] │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman file list
Usage: pinman file list [OPTIONS] File formats Pinman supports, from the live declarations. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --domain [platform|pinball|all] Only formats for this │ │ domain, or all. [default: │ │ platform] │ │ --all Every domain. Not with │ │ --domain. │ │ --wip Also list │ │ work-in-progress formats │ │ this release does not │ │ support yet. │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole │ │ run; default quiet — │ │ PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman file show
Usage: pinman file show [OPTIONS] FORMAT Everything Pinman declares about one file format. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FMT FORMAT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal
Usage: pinman journal [OPTIONS] COMMAND [ARGS]... Journal entries: log, inspect, edit, and share. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Entries ───────────────────────────────────────────────────────────────────┐ │ list List recent journal entries (newest first). │ │ show Show one journal entry's detail. │ │ create Create a journal entry, optionally with a linked capture. │ │ edit Edit a journal entry's title, note, zones or software. │ │ delete Delete a journal entry, and with `--with-capture` its linked │ │ capture. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Export ────────────────────────────────────────────────────────────────────┐ │ share Export journal entries as a markdown report. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal create
Usage: pinman journal create [OPTIONS] Create a journal entry, optionally with a linked capture. Use `--capture` to run a capture and link it to the entry. The capture levers (`--backup/--no-backup`, `--granularity file|settings`, `--scope tracked|discovery`) apply only with `--capture`; this is a capture-creating entry point, so it takes the full shared lever decorator. `--zone`/`--software` must be defined in the schema; `--auto-associate` (default) adds the Zones and Software references of the tracked items the capture changed. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --title TEXT Short title │ │ (required). [required] │ │ --note TEXT Optional note / │ │ annotation. │ │ --zone TAG Zone tag (repeatable). │ │ --software ID Software reference │ │ (repeatable). │ │ --auto-associate/--n Associate the entry │ │ o-auto-associate with the Zones and │ │ Software of changed │ │ tracked items. │ │ [default: │ │ auto-associate] │ │ --capture Run a capture and link │ │ it to this entry. │ │ --backup/--no-backup Back up a restorable │ │ copy of changed bytes │ │ (Savepoint). Off = │ │ metadata-only │ │ Checkpoint. [default: │ │ no-backup] │ │ --granularity [file|settings] Granularity: 'file' │ │ (file-level only — the │ │ 'File' kinds) or │ │ 'settings' (full │ │ per-setting detail). │ │ [default: file] │ │ --scope [tracked|discovery] Scope: 'tracked' │ │ (schema-tracked items │ │ only) or 'discovery' │ │ (also find untracked │ │ items — the '+' │ │ kinds). [default: │ │ tracked] │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default │ │ quiet — PINMAN_VERBOSE │ │ env var sets the │ │ default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal delete
Usage: pinman journal delete [OPTIONS] [ID] Delete a journal entry, and with `--with-capture` its linked capture. Select by positional ID or `--latest` (the newest entry). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item (mutually exclusive with a │ │ positional ID/NAME). │ │ --with-capture Also delete the entry's linked capture │ │ (chain-safe, like `capture delete`). │ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal edit
Usage: pinman journal edit [OPTIONS] [ID] Edit a journal entry's title, note, zones or software. Select by positional ID or `--latest` (the newest entry). Only the fields you pass change: `--zone` replaces the zones, `--software` replaces the software, `--clear-associations` empties both. Values must be defined in the schema. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --title TEXT New title. │ │ --note TEXT New note / annotation │ │ (replaces existing). │ │ --zone TAG Replace the zones with │ │ these (repeatable). Omit to │ │ leave zones unchanged. │ │ --software ID Replace the software with │ │ these (repeatable). Omit to │ │ leave software unchanged. │ │ --clear-associations Remove all zones and │ │ software (not with │ │ --zone/--software). │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal list
Usage: pinman journal list [OPTIONS] List recent journal entries (newest first). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --source [note|system] Filter by entry source. │ │ --search TEXT Text search in title / note. │ │ --from [%Y-%m-%d] First local day (YYYY-MM-DD). │ │ --to [%Y-%m-%d] Last local day (YYYY-MM-DD). │ │ --zone TAG Only entries with this zone │ │ (repeatable; any match; a │ │ category matches its │ │ children). │ │ --software ID Only entries with this │ │ software (repeatable; any │ │ match). │ │ --limit INTEGER Max entries to show. [default: │ │ 20] │ │ --offset INTEGER Pagination offset. [default: │ │ 0] │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman journal show
Usage: pinman journal show [OPTIONS] [ID] Show one journal entry's detail. Select by positional ID or `--latest` (the newest entry). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TARGET [ID] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --latest Select the newest item │ │ (mutually exclusive with a │ │ positional ID/NAME). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit
Usage: pinman kit [OPTIONS] COMMAND [ARGS]... Manage content kits (author, install, import into a project). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Library ───────────────────────────────────────────────────────────────────┐ │ list List installed kits and the kits the active project has added. │ │ install Install a kit from a .zip (or directory) onto this machine's hub │ │ store. │ │ uninstall Uninstall a kit from this machine's hub store (inverse of │ │ install). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Project ───────────────────────────────────────────────────────────────────┐ │ import Import an installed kit into the active project (schema merged; │ │ profiles; requires first). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Authoring ─────────────────────────────────────────────────────────────────┐ │ create Scaffold an empty kit skeleton NAME/ for an author to fill. │ │ build Build kit NAME into a distributable <name>-kit-<version>.zip. │ │ check Validate a project's kit membership (resolvable, requires, drift, │ │ collisions). │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit build
Usage: pinman kit build [OPTIONS] NAME Build kit NAME into a distributable <name>-kit-<version>.zip. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --version TEXT Override the built artifact's │ │ version. │ │ --out TEXT Output directory (default: │ │ cwd). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit check
Usage: pinman kit check [OPTIONS] Validate a project's kit membership (resolvable, requires, drift, collisions). Exit codes for scripting: 0 = every invariant holds, 1 = at least one violation (the report names which). A validation command that always exited 0 could not be gated on. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Project to check (default: │ │ active). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit create
Usage: pinman kit create [OPTIONS] NAME Scaffold an empty kit skeleton NAME/ for an author to fill. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --out TEXT Parent directory (default: │ │ cwd). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit import
Usage: pinman kit import [OPTIONS] NAME Import an installed kit into the active project (schema merged; profiles; requires first). Idempotent: importing a kit the project already has is a no-op — for both the same version and a newer one. Pass --force to (re-)merge its schema, re-asserting the kit's authored values over your local edits; --force is also how you apply an upgrade. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit install
Usage: pinman kit install [OPTIONS] SOURCE Install a kit from a .zip (or directory) onto this machine's hub store. Machine scope: makes the kit resolvable by name for every project. Pass --import to also import it into the active project in one step (community/beta content shows its disclaimer at the `import` step, where its code runs). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * SOURCE PATH [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --import Also import it into the active │ │ project. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit list
Usage: pinman kit list [OPTIONS] List installed kits and the kits the active project has added. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman kit uninstall
Usage: pinman kit uninstall [OPTIONS] NAME Uninstall a kit from this machine's hub store (inverse of install). Removes the kit's library copy. A project that already imported the kit keeps its merged schema (projects are disposable). A shipped master kit cannot be uninstalled. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log
Usage: pinman log [OPTIONS] COMMAND [ARGS]... Application log commands. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Log ───────────────────────────────────────────────────────────────────────┐ │ show Show the application log (optionally filtered by level). │ │ clear Clear the application log. │ │ note Record a note in the log (manual test-sequence marker). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ list List the log files, current and rotated, newest first. │ │ rotate Save the current log as a timestamped copy and start it fresh. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log clear
Usage: pinman log clear [OPTIONS] Clear the application log. Destructive: confirms in a terminal, refuses non-interactively without ``--force`` (exit 2). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --all Also delete rotated copies of │ │ the log. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log list
Usage: pinman log list [OPTIONS] List the log files, current and rotated, newest first. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log note
Usage: pinman log note [OPTIONS] TEXT Record a note in the log (manual test-sequence marker). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * TEXT TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log rotate
Usage: pinman log rotate [OPTIONS] Save the current log as a timestamped copy and start it fresh. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman log show
Usage: pinman log show [OPTIONS] Show the application log (optionally filtered by level). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --level [debug|detail|info|warn Show only lines at this │ │ ing|error|critical] level (e.g. info | debug │ │ | error). │ │ --file TEXT A log named by `pinman │ │ log list` (default: the │ │ current pinman.log). │ │ --lines INTEGER RANGE [x>=0] Show the last N lines (0 │ │ = the whole file). │ │ [default: 1000] │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port
Usage: pinman port [OPTIONS] COMMAND [ARGS]... Manage ports: topology, labeling, and device expectations. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Ports ─────────────────────────────────────────────────────────────────────┐ │ list Show port topology with connected devices and labels. │ │ label Set or clear the user-assigned label on a port. │ │ expect Pin a device as expected on a port, or clear the expectation. │ │ reset Clear all saved port data from the Computer. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ USB ───────────────────────────────────────────────────────────────────────┐ │ scan Scan raw USB devices currently connected (training-wizard helper). │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port expect
Usage: pinman port expect [OPTIONS] PORT_ID [DEVICE_NAME] Pin a device as expected on a port, or clear the expectation. PORT_ID is the ID, label or name `port list` shows. DEVICE_NAME is the device name or numeric ID. Omit to clear the pin. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * PORT_ID TEXT [required] │ │ DEVICE_NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port label
Usage: pinman port label [OPTIONS] PORT_ID [LABEL] Set or clear the user-assigned label on a port. PORT_ID is the ID, label or name `port list` shows, or a USB location `port scan -v` shows that detect has not recorded yet. LABEL is the new name. Omit LABEL to clear it. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * PORT_ID TEXT [required] │ │ LABEL TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port list
Usage: pinman port list [OPTIONS] Show port topology with connected devices and labels. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port reset
Usage: pinman port reset [OPTIONS] Clear all saved port data from the Computer. Removes accumulated port history so the next 'detect' starts fresh. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman port scan
Usage: pinman port scan [OPTIONS] Scan raw USB devices currently connected (training-wizard helper). Lists all USB classes: HID, serial/COM, audio, and others. A live hardware scan, independent of the device table. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman power
Usage: pinman power [OPTIONS] COMMAND [ARGS]... Power control for this machine: shut down, reboot. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Power ─────────────────────────────────────────────────────────────────────┐ │ off Shut down this machine. │ │ reboot Reboot this machine. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman power off
Usage: pinman power off [OPTIONS] Shut down this machine. From source this only PRETENDS — see `PRETEND_REBOOT`. A frozen build is the one that really powers the machine off. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --allow-writes Write to the machine even though machine_readonly │ │ is enabled. │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman power reboot
Usage: pinman power reboot [OPTIONS] Reboot this machine. From source this only PRETENDS — see `PRETEND_REBOOT`. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --allow-writes Write to the machine even though machine_readonly │ │ is enabled. │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile
Usage: pinman profile [OPTIONS] COMMAND [ARGS]... Manage reusable desired-state recipes. Profiles express intent; captures supply authoring evidence and live state supplies comparison context. Authoring tools live under `pinman profile authoring`; per-profile target management under `pinman profile target`. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Apply ─────────────────────────────────────────────────────────────────────┐ │ preview Preview what applying a profile would change. │ │ apply Apply a profile's target values to live configuration. │ │ status Check whether a profile's targets match live values. │ │ refresh Refresh capture values for a profile's target locations. │ │ undo Undo the most recent apply for a profile (restore previous │ │ values). │ │ revert Revert disruptive (display) changes from an apply, keeping other │ │ changes. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Manage ────────────────────────────────────────────────────────────────────┐ │ list List all profiles from the registry. │ │ show Show profile details (metadata, inputs, targets). │ │ rename Rename a profile (.py file + registry + history + journal │ │ cascade). │ │ edit Edit a profile's `.py` script. │ │ delete Delete a profile (.py file + registry entry). │ │ history Show apply history for a profile (or all profiles). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Author ────────────────────────────────────────────────────────────────────┐ │ compose Generate one profile whose select choices use source-profile │ │ target values. │ │ collect Generate a literal profile from reviewed selected items. │ │ relink Reattach history after an out-of-band profile rename. │ │ sync Reconcile the profile registry with the on-disk profiles │ │ directory. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Sub-groups ────────────────────────────────────────────────────────────────┐ │ authoring Author profile scripts: scaffold · inspect compiled intent · │ │ lint. │ │ target Manage a profile's targets: list · add · remove. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ allow-full-python Trust one exact Profile Script version with full Python. │ │ disable Remove a profile from normal top-level use. │ │ edit-history List, inspect, restore, or clean saved profile source │ │ versions. │ │ enable Make a profile available as a top-level action. │ │ pin Add a profile to the Dashboard. │ │ restrict Return a Profile Script to Restricted mode. │ │ run Run a sequenced profile — its steps, holds and commands, │ │ in order. │ │ unpin Remove a profile from the Dashboard. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile allow-full-python
Usage: pinman profile allow-full-python [OPTIONS] NAME_OR_PATH Trust one exact Profile Script version with full Python. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME_OR_PATH TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile apply
Usage: pinman profile apply [OPTIONS] NAME Apply a profile's target values to live configuration. `--dry-run` renders a real preview (no changes). Disruptive changes (e.g. display settings) prompt for confirmation; `--force` skips the prompt, and a non-interactive apply of a disruptive profile refuses without `--force`. When `machine_readonly` is enabled the apply is previewed instead — pass `--allow-writes` to authorize this one invocation to write anyway. With `require_savepoint` on, a file no Savepoint holds as it is now is refused: `--take-savepoint` takes one first, `--overwrite-unsaved` changes it anyway. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --input TEXT Interface value in key=value │ │ format; repeat for multiple │ │ inputs. Values are coerced │ │ and validated by the profile │ │ definition. │ │ --no-check Skip pre-check (allow │ │ partial apply on errors). │ │ --no-refresh Skip refresh (use cached │ │ values). │ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --allow-writes Write to the machine even │ │ though machine_readonly is │ │ enabled. │ │ --take-savepoint Take a Savepoint first, so │ │ what this changes can be put │ │ back. │ │ --overwrite-unsaved Change files even when no │ │ Savepoint holds them as they │ │ are now. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile collect
Usage: pinman profile collect [OPTIONS] NAME Generate a literal profile from reviewed selected items. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --items TEXT Reviewed JSON target │ │ mappings; literal sets │ │ require location and value. │ │ [required] │ │ --zone TEXT Zone tag (can repeat). │ │ --description TEXT Profile description. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile compose
Usage: pinman profile compose [OPTIONS] NAME Generate one profile whose select choices use source-profile target values. This creates choices, not an assembly. Use p.include() or the Assembly tab when the child profiles should remain ordered components. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --from TEXT Source profile .py file │ │ used as one choice; repeat │ │ in desired choice order. │ │ [required] │ │ --zone TEXT Zone tag (can repeat). │ │ --description TEXT Profile description. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile delete
Usage: pinman profile delete [OPTIONS] NAME Delete a profile (.py file + registry entry). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile disable
Usage: pinman profile disable [OPTIONS] NAME Remove a profile from normal top-level use. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile edit
Usage: pinman profile edit [OPTIONS] NAME Edit a profile's `.py` script. With no options, opens the script in your `$EDITOR`. With `--from-file`, replaces the source from a file (non-interactive). The previous version is snapshotted to `_history/` only when the source actually changes, and the result is re-validated. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --from-file FILE Replace the profile's source with this │ │ file's contents (non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile edit-history
Usage: pinman profile edit-history [OPTIONS] NAME List, inspect, restore, or clean saved profile source versions. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --limit INTEGER RANGE [x>=0] Max versions to list. │ │ --show VERSION Show one saved source │ │ version. │ │ --restore VERSION Restore one saved source │ │ version. │ │ --undo Undo the last saved source │ │ edit. │ │ --clean Apply edit-history │ │ retention now. │ │ --keep INTEGER RANGE [x>=0] With --clean: keep at most │ │ N newest versions (default: │ │ 50). │ │ --older-than INTEGER RANGE [x>=0] With --clean: remove │ │ versions older than N days │ │ (default: 180). │ │ --force -f Skip the confirmation │ │ prompt (and authorize the │ │ op when non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile enable
Usage: pinman profile enable [OPTIONS] NAME Make a profile available as a top-level action. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile history
Usage: pinman profile history [OPTIONS] [NAME] Show apply history for a profile (or all profiles). With `--clean --older-than N`, delete apply-history records older than N days instead of listing. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --limit INTEGER Max records to show. │ │ --clean Delete old history records │ │ (requires --older-than). │ │ --older-than INTEGER With --clean: delete records │ │ older than N days. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile list
Usage: pinman profile list [OPTIONS] List all profiles from the registry. By default reconciles the registry with the on-disk profiles directory before listing. Pass `--no-sync` to read the DB as-is. Live: `=` in sync, `~` drift, `?` unknown, `x` missing, `-` empty; blank means a profile with required inputs and no apply history (no target values to check against yet). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --zone TEXT Filter by zone (can repeat). │ │ --no-sync Skip the implicit registry │ │ sync (read DB as-is). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile pin
Usage: pinman profile pin [OPTIONS] NAME Add a profile to the Dashboard. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile preview
Usage: pinman profile preview [OPTIONS] NAME Preview what applying a profile would change. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --input TEXT Interface value in key=value │ │ format; repeat for multiple │ │ inputs. Values are coerced and │ │ validated by the profile │ │ definition. │ │ --no-refresh Skip refresh (use cached │ │ values). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile refresh
Usage: pinman profile refresh [OPTIONS] [NAME] Refresh capture values for a profile's target locations. Pass `--all` to refresh every profile (deduplicated) and report their status. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --input TEXT Interface value in key=value │ │ format; repeat for multiple │ │ inputs. Values are coerced and │ │ validated by the profile │ │ definition. │ │ --all Refresh all profiles │ │ (deduplicated) and show │ │ status. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile 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 restrict
Usage: pinman profile restrict [OPTIONS] NAME_OR_PATH Return a Profile Script to Restricted mode. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME_OR_PATH TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile revert
Usage: pinman profile revert [OPTIONS] NAME Revert disruptive (display) changes from an apply, keeping other changes. Unlike `undo` (which restores every setting), `revert` rolls back only the disruptive WinRT display changes from a history record — the CLI counterpart of the UI's post-apply "Revert" countdown. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --record-id INTEGER Specific history record ID to │ │ revert. │ │ --allow-writes Write to the machine even │ │ though machine_readonly is │ │ enabled. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile run
Usage: pinman profile run [OPTIONS] NAME Run a sequenced profile — its steps, holds and commands, in order. A run is cancellable: Ctrl+C stops it between steps or during a hold, and the process exits 130. Use ``pinman profile apply`` for a profile that carries desired state instead of steps. ``--allow-writes`` is the same per-invocation read-only override apply takes; without it a stock install (``machine_readonly`` on) refuses every run. ``--take-savepoint`` and ``--overwrite-unsaved`` answer ``require_savepoint``, as on apply. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --allow-writes Write to the machine even │ │ though machine_readonly is │ │ enabled. │ │ --take-savepoint Take a Savepoint first, so │ │ what this changes can be put │ │ back. │ │ --overwrite-unsaved Change files even when no │ │ Savepoint holds them as they │ │ are now. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile show
Usage: pinman profile show [OPTIONS] NAME Show profile details (metadata, inputs, targets). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile status
Usage: pinman profile status [OPTIONS] NAME Check whether a profile's targets match live values. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --input TEXT Interface value in key=value │ │ format; repeat for multiple │ │ inputs. Values are coerced and │ │ validated by the profile │ │ definition. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile sync
Usage: pinman profile sync [OPTIONS] Reconcile the profile registry with the on-disk profiles directory. Adds new files, restores rows whose files reappeared, refreshes metadata for modified files, and marks rows whose files were deleted as `state='missing'`. With `--remove-missing`, missing rows are deleted with their apply history. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --dry-run Preview what would change │ │ without applying it. │ │ --remove-missing Delete registry rows (and │ │ their apply history) for files │ │ no longer on disk. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile target
Usage: pinman profile target [OPTIONS] COMMAND [ARGS]... Manage a profile's targets: list · add · remove. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Targets ───────────────────────────────────────────────────────────────────┐ │ list List a profile's targets (property + file targets). │ │ add Add a target (by LOCATION, e.g. fs:/path/file.ini#Sec/Key) to a │ │ profile's script. │ │ remove Remove a target (by LOCATION) from a profile's script. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile target add
Usage: pinman profile target add [OPTIONS] NAME LOCATION Add a target (by LOCATION, e.g. fs:/path/file.ini#Sec/Key) to a profile's script. The item type is inferred from the location's schema at apply time, so it is not specified here. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ * --value TEXT Target value to set. │ │ [required] │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile target list
Usage: pinman profile target list [OPTIONS] NAME List a profile's targets (property + file targets). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile target remove
Usage: pinman profile target remove [OPTIONS] NAME LOCATION Remove a target (by LOCATION) from a profile's script. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ │ * LOCATION TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile undo
Usage: pinman profile undo [OPTIONS] NAME Undo the most recent apply for a profile (restore previous values). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --record-id INTEGER Specific history record ID │ │ to undo. │ │ --allow-writes Write to the machine even │ │ though machine_readonly is │ │ enabled. │ │ --take-savepoint Take a Savepoint first, so │ │ what this changes can be put │ │ back. │ │ --overwrite-unsaved Change files even when no │ │ Savepoint holds them as they │ │ are now. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman profile unpin
Usage: pinman profile unpin [OPTIONS] NAME Remove a profile from the Dashboard. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project
Usage: pinman project [OPTIONS] COMMAND [ARGS]... Manage pinman projects (independent data homes on this machine). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Projects ──────────────────────────────────────────────────────────────────┐ │ create Create a pinman project (create DB, import + adopt kits, configure │ │ backups_root). │ │ use Switch the active project. │ │ list List projects on this machine (active is marked; api-running │ │ noted). │ │ current Show the current (active) project and its resolved home. │ │ rename Rename a project (label only; the home directory path is │ │ unchanged). │ │ delete Delete a project: delete its home directory and its catalog entry. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project create
Usage: pinman project create [OPTIONS] [NAME] Create a pinman project (create DB, import + adopt kits, configure backups_root). Idempotent: an existing database is migrated to head rather than recreated. Registers the project in the env's catalog and makes it active, recording its adopted kits. Without --kit, the 'blank' kit is adopted (realm-root scaffolding only — a browsable, nothing-tracked project). The platform baseline (OS software catalog + reference data) is always present without adoption. With --from-project, the new project imports a schema cloned from a live one and adopts no kits. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --home DIRECTORY Home directory for a new │ │ project (prod only). Defaults │ │ to <hub>/projects/<name>. │ │ --backups DIRECTORY Path to the backups root │ │ directory. Defaults to a │ │ per-project path when │ │ prompted. │ │ --backups-default Use the default in-home │ │ backups root without prompting │ │ (unattended installs). Ignored │ │ if --backups is given. │ │ --kit TEXT Kit name whose schema/ to │ │ import + adopt; repeatable, in │ │ order. Without it, the 'blank' │ │ kit (realm-root scaffolding, │ │ nothing tracked) is adopted. │ │ --from-project TEXT Clone a live project's schema │ │ into the new project │ │ (experimentation; the source │ │ is untouched). Schema-only — │ │ no fixtures, config, or │ │ captures. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project current
Usage: pinman project current [OPTIONS] Show the current (active) project and its resolved home. Prints "(none)" when no project is selected, and marks one that is selected but not created yet. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project delete
Usage: pinman project delete [OPTIONS] NAME Delete a project: delete its home directory and its catalog entry. Destructive: the home (db, config, profiles, in-home backups) is deleted. Backups relocated outside the home are untouched. Deleting the *active* project offers to stop the tray and its services first (they hold the home open), then the alphabetically-first remaining project becomes active and the tray restarts onto it. If it was the only project, no project is active afterwards and the tray is left stopped (create a new one to start again). With --force, a NAME the catalog doesn't know deletes any leftover home directory of that name — logs and all — or does nothing if there is none. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project list
Usage: pinman project list [OPTIONS] List projects on this machine (active is marked; api-running noted). With --verbose, also lists home directories that no catalog entry claims. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project rename
Usage: pinman project rename [OPTIONS] OLD NEW Rename a project (label only; the home directory path is unchanged). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * OLD TEXT [required] │ │ * NEW TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman project use
Usage: pinman project use [OPTIONS] NAME Switch the active project. The switch only takes effect when the services next start, so while the service is running this offers to stop it, switch, and restart it (so it comes back on the newly-selected project). Use --force to skip the prompt. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema
Usage: pinman schema [OPTIONS] COMMAND [ARGS]... Schema related commands. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inspect ───────────────────────────────────────────────────────────────────┐ │ show Show schema information. │ │ export Export schema in clean, DRY format (smart export). │ │ dump Dump schema tree structure (raw database format). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Manage ────────────────────────────────────────────────────────────────────┐ │ import Import schema definitions from a file, directory, or kit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ item Inspect and author individual schema definitions. │ │ validate Validate schema YAML independently of the active project. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema dump
Usage: pinman schema dump [OPTIONS] Dump schema tree structure (raw database format). Default (-o human) renders colorized JSON to the terminal; -o json / -o yaml emit the raw payload to stdout. Use --file to write to disk. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --file FILE Write the payload to this file │ │ as UTF-8 (default: stdout). │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema export
Usage: pinman schema export [OPTIONS]
Export schema in clean, DRY format (smart export).
Default (-o human) renders colorized YAML to the terminal; -o yaml / -o json
emit the raw payload to stdout (pipe-friendly). Use --file to write to disk.
Examples:
Export everything for specific software (entry + associated items):
pinman schema export --software dof -o yaml --file dof.yaml
Export only the software: section, filtered to nvidia entries:
pinman schema export --section software --software nvidia -o yaml --file
core_nvidia.yaml
Pipe JSON to another tool:
pinman schema export --by-software -o json | jq '.items'
Export one item's subtree for a support repair (edit, then re-apply
scoped):
pinman schema export --item 'winreg:/HKEY_CURRENT_USER/Software/MyApp' \
-o yaml --file myapp.yaml
pinman schema import myapp.yaml --replace \
--item 'winreg:/HKEY_CURRENT_USER/Software/MyApp'
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --file FILE Write the payload to this file │
│ as UTF-8 (default: stdout). │
│ --by-software Organize items by primary │
│ software_ref at top level │
│ using virtual wrappers │
│ --section [software|items] Export only this section │
│ (software: entries or items │
│ tree) │
│ --no-section [software|items] Exclude this section from │
│ export │
│ --software PATTERN Include only content matching │
│ this software ID (repeatable; │
│ "dof" means "dof:*") │
│ --no-software PATTERN Exclude content matching this │
│ software ID (repeatable; "dof" │
│ means "dof:*") │
│ --item LOCATION Export only this item's │
│ subtree as an items-only │
│ fragment (re-apply with │
│ 'schema import --replace │
│ --item LOCATION') │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman schema import
Usage: pinman schema import [OPTIONS] FILE_PATH_OR_PACKAGE Import schema definitions from a file, directory, or kit. FILE_PATH_OR_PACKAGE may be a YAML file, a directory (imports all *.yaml files found in it), or a bare kit name resolved to the kit's schema/ directory across the kit roots. Catalog-only files (software: without items:) upsert SoftwareEntry records. Default is an idempotent create-or-merge: create the schema when the project has none, else additively merge (union tags/software_refs, per-key vars/props — never deletes). Uniform across file, directory, and kit inputs. Pass --replace for a destructive sync that removes items not in the YAML. With --dry-run, the exact operation runs against an isolated project clone and reports semantic definition/declaration changes, linked rows and Capture requirements. Use '-' as the file to plan YAML from stdin. Directory and kit imports do not support --dry-run. (kit import is the guarded normal path for adopting kit content; plain schema import is the lower-level tool.) ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FILE_PATH PATH [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --name TEXT Override the schema │ │ selector in the file │ │ --replace Re-import an │ │ edited/updated YAML: │ │ destructive sync │ │ (preserves IDs, syncs │ │ tags, REMOVES items not │ │ in the YAML). Without │ │ it, import is an │ │ idempotent │ │ create-or-merge (creates │ │ the schema, or merges │ │ additively — never │ │ deletes). │ │ --no-orphan-check Skip check for orphaned │ │ tags (tags on items not │ │ in new zone_defs) │ │ --allow-itemtype-change Allow itemtype changes │ │ on existing items during │ │ --replace │ │ --item LOCATION Confine --replace to the │ │ subtree at this item │ │ location (bounded │ │ repair; nothing outside │ │ is added, updated, or │ │ deleted). Pairs with │ │ 'schema export --item'. │ │ --dry-run Preview what would │ │ change without applying │ │ it. │ │ --strict-software-refs Fail if any │ │ software_refs IDs are │ │ undefined in the catalog │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed │ │ output incl. progress │ │ logs (applies to the │ │ whole run; default quiet │ │ — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item
Usage: pinman schema item [OPTIONS] COMMAND [ARGS]... Inspect and author individual schema definitions. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ add Create one schema definition under PARENT. │ │ edit Patch guide fields, or replace a complete definition from a file. │ │ for Create and maintain structural iteration templates. │ │ list List schema definitions in hierarchy order. │ │ move Reorder one definition relative to a sibling without reparenting │ │ it. │ │ remove Remove one leaf definition and orphan its linked rows. │ │ show Show one schema definition by canonical location or #ID. │ │ var List and edit definition variables without a YAML file. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item add
Usage: pinman schema item add [OPTIONS] PARENT
Create one schema definition under PARENT.
PARENT accepts a canonical location or #ID. Common metadata can be supplied
directly; --definition-file adds advanced guide-shaped fields atomically.
--row-var creates a supported row template with the definition. Structural
for-blocks use the dedicated schema item for workflow.
Examples:
pinman schema item add '#2' --selector C/App --itemtype directory --zone
Production
pinman schema item add 'fs:/C/App' --selector hosts.csv --itemtype csv_file
--row-var HOST
pinman schema item add '#17' --selector controls --itemtype rest_service
--definition-file service.json
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PARENT TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --selector TEXT Name or relative path under │
│ PARENT. [required] │
│ * --itemtype TEXT Schema item type to create. │
│ [required] │
│ --definition-file FILE Optional YAML/JSON │
│ fragment; use '-' for │
│ stdin. Explicit flags │
│ override it. │
│ --label TEXT Human-readable label. │
│ --description TEXT Longer definition │
│ description. │
│ --zone TEXT Assign a defined Zone; │
│ repeatable. │
│ --software TEXT Assign a Software │
│ declaration ID; repeatable. │
│ --const NAME=VALUE Set a definition constant; │
│ repeatable. │
│ --row-var NAME Also create the adapter's │
│ row-placeholder child as │
│ {{NAME}}. │
│ --dry-run Preview what would change │
│ without applying it. │
│ --output -o [human|json|yaml] Output format (human | json │
│ | yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole run; │
│ default quiet — │
│ PINMAN_VERBOSE env var sets │
│ the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman schema item edit
Usage: pinman schema item edit [OPTIONS] ITEM
Patch guide fields, or replace a complete definition from a file.
Without --definition-file, omitted fields are preserved. A Definition file
remains a complete replacement: its omissions clear content, then explicit
flags override it. All changes are adapter-validated and atomic.
Repeat --set/--set-json to validate jointly-required fields atomically.
Examples:
pinman schema item edit 'fs:/C/App' --set follow_links=false
pinman schema item edit '#8' --set-json primary_key='["system","name"]'
pinman schema item edit '#18' --set path_prefix=/api/controls --set
service=api
pinman schema item edit '#19' --set-json
read='{"path":"/api/controls","pointer":"volume"}'
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * ADDRESS ITEM [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --definition-file FILE Optional full YAML/JSON │
│ replacement; use '-' for │
│ stdin. Flags override it. │
│ --set FIELD=VALUE Set a guide field using a │
│ typed scalar; adapter fields │
│ need no schema_props prefix. │
│ --set-json FIELD=JSON Set a list, mapping, or │
│ explicitly JSON-typed guide │
│ field; repeatable. │
│ --unset FIELD Remove an explicit guide field │
│ so it clears or returns to │
│ inheritance; repeatable. │
│ --const NAME=VALUE Set or replace one definition │
│ constant; repeatable. │
│ --remove-const NAME Remove one definition │
│ constant; repeatable. │
│ --dry-run Preview what would change │
│ without applying it. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman schema item for
Usage: pinman schema item for [OPTIONS] COMMAND [ARGS]... Create and maintain structural iteration templates. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ add Create a for block and its required template child atomically. │ │ edit Edit a for binding without replacing its template subtree. │ │ remove Remove a for block and its complete template subtree. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item for add
Usage: pinman schema item for add [OPTIONS] PARENT
Create a for block and its required template child atomically.
PARENT accepts a canonical location or #ID. Nest another block by using an
existing template child as PARENT. --before controls first-match priority.
Example:
pinman schema item for add 'fs:/C/App/codecs' --var CODEC --pattern
'*.codec' --itemtype file
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PARENT TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ * --var TEXT Iteration variable name. │
│ [required] │
│ * --pattern TEXT Adapter match pattern for │
│ the variable. [required] │
│ --selector TEMPLATE Template selector; defaults │
│ to '{{VAR}}'. │
│ * --itemtype TEXT Item type for the template │
│ definition. [required] │
│ --definition-file FILE Optional YAML/JSON fragment │
│ for the template; use '-' │
│ for stdin. │
│ --before SIBLING Insert the block before │
│ this sibling location or │
│ #ID. │
│ --dry-run Preview what would change │
│ without applying it. │
│ --output -o [human|json|yaml] Output format (human | json │
│ | yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole run; │
│ default quiet — │
│ PINMAN_VERBOSE env var sets │
│ the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman schema item for edit
Usage: pinman schema item for edit [OPTIONS] FOR_ITEM
Edit a for binding without replacing its template subtree.
Renaming a variable updates {{VAR}} references and descendant template
locations while preserving definition IDs.
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * ADDRESS FOR_ITEM [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --var TEXT Rename the iteration variable. │
│ --pattern TEXT Replace the adapter match │
│ pattern. │
│ --dry-run Preview what would change │
│ without applying it. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman schema item for remove
Usage: pinman schema item for remove [OPTIONS] FOR_ITEM Remove a for block and its complete template subtree. A real removal requires interactive confirmation or --force. Use --dry-run to inspect every definition and linked row that would be removed. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS FOR_ITEM [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item list
Usage: pinman schema item list [OPTIONS] List schema definitions in hierarchy order. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --parent ITEM List only the immediate │ │ children of this canonical │ │ location or #ID. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item move
Usage: pinman schema item move [OPTIONS] ITEM Reorder one definition relative to a sibling without reparenting it. Specify exactly one of --before or --after. The explicit order persists and controls first-match precedence where sibling definitions overlap. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --before SIBLING Place ITEM immediately before │ │ this sibling location or #ID. │ │ --after SIBLING Place ITEM immediately after │ │ this sibling location or #ID. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item remove
Usage: pinman schema item remove [OPTIONS] ITEM Remove one leaf definition and orphan its linked rows. Definitions with children are refused; remove children first. A real removal requires interactive confirmation or --force. Use --dry-run to inspect the exact impact without authorization or mutation. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item show
Usage: pinman schema item show [OPTIONS] ITEM Show one schema definition by canonical location or #ID. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --definition Emit only the guide-shaped │ │ editable fragment (no │ │ identity, hierarchy, or │ │ children). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item var
Usage: pinman schema item var [OPTIONS] COMMAND [ARGS]... List and edit definition variables without a YAML file. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ list List editable variables owned by ITEM. │ │ remove Remove one variable owned by ITEM. │ │ set Set one string variable on ITEM. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item var list
Usage: pinman schema item var list [OPTIONS] ITEM List editable variables owned by ITEM. Inherited and Pinman-managed variables are not included. Global variables are available only when ITEM is the schema root. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --scope [const|global] Show only local constants or │ │ root globals; omitted shows │ │ every editable scope. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item var remove
Usage: pinman schema item var remove [OPTIONS] ITEM NAME Remove one variable owned by ITEM. Removing an absent variable is a successful no-op. Use --dry-run to inspect the normalized definition result without changing the project. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --scope [const|global] Remove a definition constant │ │ or a schema-root global. │ │ [default: const] │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema item var set
Usage: pinman schema item var set [OPTIONS] ITEM NAME VALUE Set one string variable on ITEM. Constants are local to ITEM. Global variables require ITEM to be the schema root; Pinman-managed platform globals are read-only. Examples: pinman schema item var set 'fs:/C/App' APP_ROOT fs:/C/App pinman schema item var set '#1' SHARED_ROOT fs:/C/Shared --scope global ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * ADDRESS ITEM [required] │ │ * NAME TEXT [required] │ │ * VALUE TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --scope [const|global] Write a definition constant or │ │ a schema-root global. │ │ [default: const] │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema show
Usage: pinman schema show [OPTIONS] Show schema information. Without flags, shows a brief summary. Use ``--device-roles`` to list hardware role definitions. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --device-roles Show device role definitions │ │ for this schema │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman schema validate
Usage: pinman schema validate [OPTIONS] FILE Validate schema YAML independently of the active project. Checks syntax and the real importer, adapter, declaration, tag and Software reference rules in a disposable database. Reports normalized issues; it does not compare against or change the active schema. Use '-' as FILE to read YAML from stdin. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FILE_PATH FILE [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service
Usage: pinman service [OPTIONS] COMMAND [ARGS]... Manage Pinman's services and the tray that supervises them. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inventory ─────────────────────────────────────────────────────────────────┐ │ list List Pinman's services and whether each is running. │ │ show Show details for one Pinman service (NAME is a service slug). │ │ status Is Pinman running? Reports the tray plus every service under it. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Lifecycle ─────────────────────────────────────────────────────────────────┐ │ start Start Pinman, or one service by NAME. │ │ stop Stop Pinman, or one service by NAME (disruptive). │ │ restart Restart Pinman, or one service by NAME (disruptive). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Operations ────────────────────────────────────────────────────────────────┐ │ logs Show recent log output for a Pinman service (NAME is a service │ │ slug). │ │ autostart Start Pinman (tray + services) automatically at Windows login. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service autostart
Usage: pinman service autostart [OPTIONS] [[on|off]]
Start Pinman (tray + services) automatically at Windows login.
With no argument, shows the current autostart status. ``on`` writes the HKCU
Run entry for this installation; ``off`` removes it. The entry is
intentionally visible in winreg captures ("User Startup Programs").
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ STATE [[on|off]] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman service list
Usage: pinman service list [OPTIONS] List Pinman's services and whether each is running. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service logs
Usage: pinman service logs [OPTIONS] {api|overlay|audio|inputs}
Show recent log output for a Pinman service (NAME is a service slug).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME {api|overlay|audio|inputs} [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --lines INTEGER Number of lines to show. │
│ [default: 100] │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman service restart
Usage: pinman service restart [OPTIONS] [[api|overlay|audio|inputs]] Restart Pinman, or one service by NAME (disruptive). With no NAME this takes the whole tree down and brings it back — the operator's one-shot recovery. With a NAME it asks the running tray to restart that one service. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME [[api|overlay|audio|inputs]] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service show
Usage: pinman service show [OPTIONS] {api|overlay|audio|inputs|scheduler}
Show details for one Pinman service (NAME is a service slug).
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * NAME {api|overlay|audio|inputs|schedu [required] │
│ ler} │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman service start
Usage: pinman service start [OPTIONS] [[api|overlay|audio|inputs]] Start Pinman, or one service by NAME. With no NAME this starts the tray, which brings up every service it supervises. With a NAME it asks the *running* tray to start that one service. ``--welcome/--no-welcome`` and ``--open-ui/--no-open-ui`` override what the tray would decide on its own — useful for an unattended start that should put nothing on screen (``--no-welcome``), or for a start that should land the user on the dashboard (``--open-ui``). Omitted, the tray's own defaults apply: welcome window shown and auto-dismissing, no browser. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME [[api|overlay|audio|inputs]] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --welcome/--no-welcome Show or suppress the │ │ welcome/QR window │ │ (default: show, │ │ auto-dismissing). │ │ --open-ui/--no-open-ui Open the dashboard in a │ │ browser once the API │ │ answers (default: don't). │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole │ │ run; default quiet — │ │ PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service status
Usage: pinman service status [OPTIONS] Is Pinman running? Reports the tray plus every service under it. The runtime answer, where `service list` is the inventory: the supervisor's own state first (nothing below it runs without it), then a line per service that isn't up. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman service stop
Usage: pinman service stop [OPTIONS] [[api|overlay|audio|inputs]] Stop Pinman, or one service by NAME (disruptive). With no NAME this stops the tray and every service under it. With a NAME the stop routes through the tray supervisor when it's running (the service stays down until started again); with no tray, a standalone service (dev) is stopped via its own shutdown endpoint, and the in-process Scheduler can't be. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ NAME [[api|overlay|audio|inputs]] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman setup
Usage: pinman setup [OPTIONS] Guided first-run: create your first project (from a tutorial, kits, or blank). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --no-start Don't offer to start Pinman at the end (the │ │ installer starts it itself). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software
Usage: pinman software [OPTIONS] COMMAND [ARGS]... Manage Software catalog definitions, detection, and inventory. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Catalog ───────────────────────────────────────────────────────────────────┐ │ list List detected software from the catalog. │ │ show Show detail for one catalog entry by name, label, or numeric ID. │ │ detect Detect software availability on the system. │ │ launch Launch an external software/tool by name, label, or numeric ID. │ │ reset Clear detected machine state without deleting catalog definitions. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ create Create a Software catalog definition without detecting machine │ │ availability. │ │ delete Delete a catalog definition and report/clean active references. │ │ edit Edit authored catalog fields while preserving detected machine │ │ state. │ │ export Export one catalog definition in reusable `software:` schema shape. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software create
Usage: pinman software create [OPTIONS] NAME Create a Software catalog definition without detecting machine availability. Supply `--label` and `--class` for common entries, or a Definition file for the complete schema-format entry. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --label TEXT Human-readable catalog label. │ │ --class TEXT Free-form software class; │ │ built-ins include application, │ │ service, driver, utility, │ │ runtime, os_builtin. │ │ --vendor TEXT Software vendor. │ │ --command TEXT Fixed launch command. │ │ --device-class TEXT Device class (repeatable). │ │ --zone TEXT Defined Zone tag (repeatable). │ │ --path TEXT Published anchor NAME=LOCATION │ │ (repeatable). │ │ --definition-file FILE YAML/JSON entry for detection │ │ rules, relationships, or full │ │ authoring. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software delete
Usage: pinman software delete [OPTIONS] NAME Delete a catalog definition and report/clean active references. Historical capture rows keep their recorded Software metadata. A real deletion requires confirmation or `--force`; detected availability state for this catalog ID is deleted with the definition. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --dry-run Preview what would change │ │ without applying it. │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software detect
Usage: pinman software detect [OPTIONS] Detect software availability on the system. Scans for known software using Uninstall registry keys, filesystem presence, and running processes. Results are persisted to the catalog. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software edit
Usage: pinman software edit [OPTIONS] NAME Edit authored catalog fields while preserving detected machine state. Field options patch the current definition. `--definition-file` performs a complete authored-field replacement; neither mode changes available, version, resolved executable paths, timestamps, or detection evidence. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --label TEXT Replace the catalog │ │ label. │ │ --class TEXT Replace the free-form │ │ software class. │ │ --vendor TEXT Replace the vendor. │ │ --clear-vendor Remove the vendor. │ │ --command TEXT Replace the fixed launch │ │ command. │ │ --clear-command Remove the fixed launch │ │ command. │ │ --device-class TEXT Replace device classes. │ │ --clear-device-classes Remove all device │ │ classes. │ │ --zone TEXT Replace Zone tags. │ │ --clear-zones Remove all Zone tags. │ │ --path TEXT Replace paths with │ │ NAME=LOCATION values. │ │ --clear-paths Remove all published │ │ paths. │ │ --definition-file FILE Atomically replace all │ │ authored catalog fields │ │ from YAML/JSON. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | │ │ json | yaml). [default: │ │ human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole │ │ run; default quiet — │ │ PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and │ │ exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software export
Usage: pinman software export [OPTIONS] NAME Export one catalog definition in reusable `software:` schema shape. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --file FILE Write the reusable definition │ │ to a YAML or JSON file. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software launch
Usage: pinman software launch [OPTIONS] NAME Launch an external software/tool by name, label, or numeric ID. NAME may be the label shown by 'software list', a catalog name, or a numeric ID. Mirrors the UI's one-click launch on the Software tab / device drawer — run a tool on the machine over SSH. Fails (exit 1) if no launch command resolves. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software list
Usage: pinman software list [OPTIONS] List detected software from the catalog. Shows software previously detected by 'pinman software detect'. By default shows only available software; pass --all to include unavailable entries. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --all Include unavailable entries. │ │ --class TEXT Filter by exact software class │ │ (free-form). │ │ --group-by [group|class] Group human output by catalog │ │ group or software class. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software reset
Usage: pinman software reset [OPTIONS] Clear detected machine state without deleting catalog definitions. Preserves every authored Software definition, including detection rules and path defaults. Run `software detect` afterward to scan again. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force -f Skip the confirmation prompt (and authorize the │ │ op when non-interactive). │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman software show
Usage: pinman software show [OPTIONS] NAME Show detail for one catalog entry by name, label, or numeric ID. NAME may be the label shown by 'software list', a catalog name, or a numeric ID. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * NAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman status
Usage: pinman status [OPTIONS] Show this machine's Overview: identity, services + health rollup. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --check Run a live status check first │ │ (device re-probe + profile │ │ value refresh). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system
Usage: pinman system [OPTIONS] COMMAND [ARGS]... This machine's system information (Machine > System). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Host ──────────────────────────────────────────────────────────────────────┐ │ show Show basic host identity (hostname, IP, OS). │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Reachability ──────────────────────────────────────────────────────────────┐ │ check Check whether this machine is reachable from other devices on the │ │ LAN. │ │ qr Show a QR code to connect another device to this machine. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ firewall Open or close Windows Firewall access to Pinman from other │ │ devices. │ │ port Show or set the TCP port Pinman's services listen on. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system check
Usage: pinman system check [OPTIONS] Check whether this machine is reachable from other devices on the LAN. Reports whether the Windows firewall allows inbound traffic on the API port — the usual reason a phone or another PC can't connect even though Pinman is running here. For whether Pinman itself is up, use `pinman service status`. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --port INTEGER TCP port to check for LAN │ │ reachability. [default: 7466] │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system firewall
Usage: pinman system firewall [OPTIONS] [[on|off]] Open or close Windows Firewall access to Pinman from other devices. With no argument, shows whether the pinman rule exists. ``on`` creates the "Pinman Server" inbound TCP allow rule — the same rule the installer's firewall option creates (re-running replaces it); ``off`` removes it. Changing the rule requires an administrator terminal. Browsing on this machine itself never needs this — Windows does not firewall loopback. ``--no-verify`` skips the reachability confirmation. That check runs ``netsh advfirewall firewall show rule name=all verbose``, which takes seconds on a machine with many rules — fine interactively, but the installer runs this hidden and would just appear to hang. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ STATE [[on|off]] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --port INTEGER TCP port the firewall rule │ │ allows. [default: 7466] │ │ --profiles TEXT Firewall profile(s) for the │ │ rule, comma-separated: │ │ domain, private, public. │ │ [default: private] │ │ --verify/--no-verify Confirm reachability │ │ afterwards (enumerates │ │ every firewall rule; slow). │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs │ │ (applies to the whole run; │ │ default quiet — │ │ PINMAN_VERBOSE env var sets │ │ the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system port
Usage: pinman system port [OPTIONS] [BASE_PORT] Show or set the TCP port Pinman's services listen on. With no argument, shows the base port and every service's derived port. Given a number, sets the base port: the API listens there and each sidecar takes the next port up, so one number moves the whole fleet off a busy port. The setting is machine-level (not per project) — all five processes must agree — so changing it takes effect on the next restart, and the firewall rule, being port-scoped, must be re-created to match. Each port is also tested for availability, so this is the command that answers "why won't that service start?". Setting a base whose block is already taken by another program is refused unless --force. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ BASE_PORT INTEGER │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --force Set the port even if another │ │ program already holds one of │ │ the block. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system qr
Usage: pinman system qr [OPTIONS] Show a QR code to connect another device to this machine. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --timeout INTEGER Seconds before the QR popup auto-closes │ │ (0 = stay open until closed). [default: │ │ 0] │ │ --size INTEGER QR code size in pixels. [default: 170] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress │ │ logs (applies to the whole run; default │ │ quiet — PINMAN_VERBOSE env var sets the │ │ default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman system show
Usage: pinman system show [OPTIONS] Show basic host identity (hostname, IP, OS). Minimal stub — the full Machine > System view (OS settings) is surfaced via `pinman winrt`; a dedicated system-info aggregator is a gap. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tag
Usage: pinman tag [OPTIONS] COMMAND [ARGS]... Tag definition management commands. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Tags ──────────────────────────────────────────────────────────────────────┐ │ list List all defined zone tags. │ │ create Create a new zone tag definition. │ │ rename Rename a zone tag and propagate to all items. │ │ delete Delete a zone tag definition. │ │ import Import zone tag definitions from a YAML file. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ show Show one Zone definition using case-insensitive lookup. │ │ update Update or explicitly clear Zone display metadata. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tag create
Usage: pinman tag create [OPTIONS] FULLNAME
Create a new zone tag definition.
FULLNAME uses ``category:name`` syntax (e.g., Audio, Audio:Music).
Examples:
pinman tag create Audio
pinman tag create Audio:Music --label "Game Music"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * FULLNAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --label TEXT Display label │
│ --description TEXT Description │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman tag delete
Usage: pinman tag delete [OPTIONS] FULLNAME
Delete a zone tag definition.
Removes the tag from schema items by default, preserving historical tag data
on captures; ``--force-all`` also strips it from captures. Destructive, so it
confirms in a terminal and refuses non-interactively without ``--force`` /
``--force-all``.
Examples:
pinman tag delete Audio
pinman tag delete Audio --force
pinman tag delete Audio --force-all
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * FULLNAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --dry-run Preview what would change │
│ without applying it. │
│ --force -f Skip the confirmation prompt │
│ (and authorize the op when │
│ non-interactive). │
│ --force-all Also remove the tag from ALL │
│ items including captures (not │
│ just schema items). │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman tag import
Usage: pinman tag import [OPTIONS] FILE_PATH
Import zone tag definitions from a YAML file.
Example YAML format:
zone_defs:
- category: Audio
- category: Audio
name: Music
label: Game Music
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * FILE_PATH FILE [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --replace Update existing tag │
│ definitions instead of │
│ skipping them. │
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman tag list
Usage: pinman tag list [OPTIONS] List all defined zone tags. By default, shows tag definitions. Use ``--scan`` to show actual tags on items, highlighting any that don't have definitions (orphaned tags). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --tree Display hierarchically by │ │ category │ │ --scan Scan items for actual tags │ │ (not just definitions) │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tag rename
Usage: pinman tag rename [OPTIONS] OLD_FULLNAME NEW_FULLNAME
Rename a zone tag and propagate to all items.
Works for both defined tags (with definitions) and orphan tags (tags on items
without definitions). Renaming is non-destructive, so it runs without a
confirmation prompt.
Examples:
pinman tag rename Audio Sound
pinman tag rename Audio:Music Audio:Soundtrack
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * OLD_FULLNAME TEXT [required] │
│ * NEW_FULLNAME TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json|yaml] Output format (human | json | │
│ yaml). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs (applies │
│ to the whole run; default │
│ quiet — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman tag show
Usage: pinman tag show [OPTIONS] FULLNAME Show one Zone definition using case-insensitive lookup. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FULLNAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tag update
Usage: pinman tag update [OPTIONS] FULLNAME Update or explicitly clear Zone display metadata. This does not rename the tag or change its uses; use `tag rename` for that. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * FULLNAME TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --label TEXT Replace the display label. │ │ --clear-label Remove the display label. │ │ --description TEXT Replace the description. │ │ --clear-description Remove the description. │ │ --dry-run Preview what would change │ │ without applying it. │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial
Usage: pinman tutorial [OPTIONS] COMMAND [ARGS]... Manage pinman tutorials (seed + step disposable teaching projects). ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Tutorials ─────────────────────────────────────────────────────────────────┐ │ list List installable tutorials (bundled + installed) and the projects │ │ seeded from them. │ │ install Seed a project from a tutorial (bundled/installed id, or a │ │ tutorial directory path). │ │ drift Apply DRIFT — a change to the tutorial's world, as if it happened │ │ behind Pinman's back. │ │ goto Re-seed a tutorial-backed project to CHAPTER's starting state, or │ │ list the chapters. │ │ docs Open a tutorial's installed offline docs (default: the guide). │ │ demo Open the Pinman Demo Manager, a window for driving a tutorial's │ │ chapters. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Authoring ─────────────────────────────────────────────────────────────────┐ │ verify Authoring QA: does this project match what `goto CHAPTER` would │ │ produce? │ │ package Build tutorial TUTORIAL into a distributable │ │ <id>-tutorial-<version>.zip. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Commands ──────────────────────────────────────────────────────────────────┐ │ scene Read a demo scene's current values from a tutorial-backed project. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial demo
Usage: pinman tutorial demo [OPTIONS] Open the Pinman Demo Manager, a window for driving a tutorial's chapters. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial docs
Usage: pinman tutorial docs [OPTIONS] [TUTORIAL] [DOC] Open a tutorial's installed offline docs (default: the guide). With no TUTORIAL, uses the tutorial that seeded --project (or the active project). DOC picks a shipped doc by name (extension optional; html wins over md): html opens in your browser, markdown renders in the terminal. The guide is a self-contained local HTML file and needs no network connection. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TUTORIAL_ID [TUTORIAL] │ │ DOC TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Tutorial-backed project │ │ (default: active). │ │ --no-open Print the doc path without │ │ opening it. │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial drift
Usage: pinman tutorial drift [OPTIONS] [DRIFT] Apply DRIFT — a change to the tutorial's world, as if it happened behind Pinman's back. Edits source files, plus machine state (registry keys, system audio) where the story calls for it. Nothing is refreshed or captured for you: that's your move — run a refresh or take a capture afterward and watch the drift surface in Pinman. Applies only that drift, on top of wherever the project is now. Your captures and history are untouched and Pinman can keep running. If the files it changes were edited by hand, it stops without writing anything and points you at `pinman tutorial goto`. DRIFT is a drift name, or a chapter name/number — a chapter that performs several drifts applies them all, in order. With no DRIFT, lists the chapters declared by the project's origin tutorial with their drifts, numbered. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ DRIFT [DRIFT] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Project to drift (default: │ │ active). │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial goto
Usage: pinman tutorial goto [OPTIONS] [CHAPTER] Re-seed a tutorial-backed project to CHAPTER's starting state, or list the chapters. For joining a tutorial part-way through: the project is wiped and rebuilt, then the tutorial replays the earlier chapters' Pinman work and drift, so you land where a learner who did them by hand would be. **This discards the work you have done** — to advance without losing it, use `pinman tutorial drift`. With no CHAPTER, lists the chapters declared by the project's origin tutorial, numbered. CHAPTER is a chapter name or one of those numbers. Re-seeding offers to stop the tray and its services first — the seed leaves the target active, and a server left running would keep serving its old one. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ CHAPTER TEXT │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Project to re-seed (default: │ │ active). │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial install
Usage: pinman tutorial install [OPTIONS] [TUTORIAL] Seed a project from a tutorial (bundled/installed id, or a tutorial directory path). Idempotent: re-running re-seeds the same project to baseline. Destructive on the target project (its home is wiped and re-seeded). Seeding any project offers to stop the tray and its services first — the seed leaves the target active, and a server left running would keep serving its old one. With no TUTORIAL, lists the installable tutorials (same as `tutorial list`). ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ TUTORIAL [TUTORIAL] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Target project (default: the │ │ tutorial id). │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial list
Usage: pinman tutorial list [OPTIONS] List installable tutorials (bundled + installed) and the projects seeded from them. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial package
Usage: pinman tutorial package [OPTIONS] TUTORIAL Build tutorial TUTORIAL into a distributable <id>-tutorial-<version>.zip. Author-time only. drifts/ ships (the learner runs those scripts); __pycache__ and docs/authoring/ are excluded. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * TUTORIAL TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --version TEXT Override the built artifact's │ │ version. │ │ --out TEXT Output directory (default: │ │ cwd). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial scene
Usage: pinman tutorial scene [OPTIONS] DRIFT Read a demo scene's current values from a tutorial-backed project. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * DRIFT TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Tutorial-backed project │ │ (default: active). │ │ --output -o [human|json|yaml] Output format (human | json | │ │ yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env var │ │ sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman tutorial verify
Usage: pinman tutorial verify [OPTIONS] CHAPTER Authoring QA: does this project match what `goto CHAPTER` would produce? Walk a chapter by hand, then verify before writing the next one. It fingerprints your project, replays `seed.py` to CHAPTER in a throwaway project, and reports every difference — so a guide whose steps have drifted from the seed recipe fails here instead of under a learner weeks later. Read-only on your machine and your project: the replay runs with machine drift suppressed, and the scratch project is always removed. Chapters declare machine state through `expect_machine()`, which is checked live — a differential cannot see it, since both projects share one registry. Declines outright once a `verify.self_contained` chapter falls behind CHAPTER: seed.py never replays one, so the diff would be its whole content. Exits non-zero on any difference. ┌─ Arguments ─────────────────────────────────────────────────────────────────┐ │ * CHAPTER TEXT [required] │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --project TEXT Project to verify (default: │ │ active). │ │ --include-untracked Compare untracked items too │ │ (for tutorials that teach │ │ discovery). │ │ --force -f Skip the confirmation prompt │ │ (and authorize the op when │ │ non-interactive). │ │ --output -o [human|json|yaml] Output format (human | json │ │ | yaml). [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output │ │ incl. progress logs (applies │ │ to the whole run; default │ │ quiet — PINMAN_VERBOSE env │ │ var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman winreg
Usage: pinman winreg [OPTIONS] COMMAND [ARGS]... Windows registry power tools (show, search, extract, diff, blacklist…). A CLI-only superset of the UI. Reads the live registry or cached `.reg` dumps; the `blacklist` and `discover` sub-groups manage filtering patterns and before/after change discovery. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Inspect ───────────────────────────────────────────────────────────────────┐ │ show Display a winreg key's values and subkeys. │ │ search Search for keys/values matching a pattern. │ │ inventory List winreg: entries from the schema and check if they exist on │ │ the system. │ │ stats Show winreg statistics. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Extract & Diff ────────────────────────────────────────────────────────────┐ │ extract Extract winreg to .reg files. │ │ diff Compare winreg data between files or against live winreg. │ │ watch Watch registry changes around an action. │ │ clear-cache Delete winreg pickle sidecars in the live extract directory. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Sub-groups ────────────────────────────────────────────────────────────────┐ │ discover Discover registry changes by comparing before/after extractions. │ │ blacklist Manage and validate winreg blacklist patterns. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist
Usage: pinman winreg blacklist [OPTIONS] COMMAND [ARGS]... Manage and validate winreg blacklist patterns. ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │ │ (applies to the whole run; default quiet — │ │ PINMAN_VERBOSE env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Patterns ──────────────────────────────────────────────────────────────────┐ │ list List all blacklist key and value patterns. │ │ add Add a pattern to the global blacklist. │ │ remove Remove a pattern from the global blacklist. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Analyze ───────────────────────────────────────────────────────────────────┐ │ test Test what a pattern matches against cached extraction data. │ │ audit Coverage report for blacklist patterns against cached extraction │ │ data. │ │ optimize Remove redundant patterns covered by a broader wildcard. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ Export ────────────────────────────────────────────────────────────────────┐ │ export Export blacklist patterns filtered by scope. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist add
Usage: pinman winreg blacklist add [OPTIONS] PATTERN
Add a pattern to the global blacklist.
PATTERN: fnmatch wildcards or regex with a 're:' prefix.
Examples:
pinman winreg blacklist add "*Cache*" --comment "Exclude cache keys"
pinman winreg blacklist add "*Timestamp*" --type value
pinman winreg blacklist add "re:.*MRU.*" --type key --comment "MRU lists"
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type [key|value] Pattern type (key or value). │
│ --comment TEXT Comment explaining the pattern. │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist audit
Usage: pinman winreg blacklist audit [OPTIONS]
Coverage report for blacklist patterns against cached extraction data.
Per-pattern hit counts (effectiveness) and dead patterns (no matches on this
machine). Requires cached extraction data — run 'pinman winreg extract
--no-filter' first if none exists.
Examples:
pinman winreg blacklist audit
pinman winreg blacklist audit --hive HKCU
pinman winreg blacklist audit --file report.json
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM|all] Which hive(s) to audit against. │
│ --file FILE Write the payload to this file │
│ as UTF-8 (default: stdout). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist export
Usage: pinman winreg blacklist export [OPTIONS]
Export blacklist patterns filtered by scope.
Useful for distributing a starter blacklist containing only patterns safe for
all machines (scope: universal).
Examples:
pinman winreg blacklist export # stdout
pinman winreg blacklist export --file starter.jsonc # file
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --scope [universal|system|candi Filter by scope. │
│ date|all] Default: universal (for │
│ distribution). │
│ --file FILE Write the payload to │
│ this file as UTF-8 │
│ (default: stdout). │
│ --output -o [human|json] Output format (human | │
│ json). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed │
│ output incl. progress │
│ logs (applies to the │
│ whole run; default quiet │
│ — PINMAN_VERBOSE env var │
│ sets the default). │
│ --help -h,-? Show this message and │
│ exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist list
Usage: pinman winreg blacklist list [OPTIONS] List all blacklist key and value patterns. Examples: pinman winreg blacklist list pinman winreg blacklist list -o json ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --output -o [human|json] Output format (human | json). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. │ │ progress logs (applies to the whole │ │ run; default quiet — PINMAN_VERBOSE │ │ env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist optimize
Usage: pinman winreg blacklist optimize [OPTIONS]
Remove redundant patterns covered by a broader wildcard.
A pattern is redundant if a broader wildcard already covers it (e.g. with
'Software\Microsoft\*' present, 'Software\Microsoft\Windows\*' is redundant).
Use --dry-run to preview; otherwise the removal is applied (force-gated).
Examples:
pinman winreg blacklist optimize --dry-run # preview redundant
pinman winreg blacklist optimize # remove (prompts)
pinman winreg blacklist optimize --force # remove (scripted)
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --blacklist-file PATH Path to blacklist file. Default: │
│ reference/winreg_blacklist.json[c]. │
│ --dry-run Preview what would change without │
│ applying it. │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist remove
Usage: pinman winreg blacklist remove [OPTIONS] PATTERN
Remove a pattern from the global blacklist.
PATTERN: the exact pattern to remove.
Examples:
pinman winreg blacklist remove "*Cache*"
pinman winreg blacklist remove "*Timestamp*" --type value
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type [key|value] Pattern type (key or value). │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg blacklist test
Usage: pinman winreg blacklist test [OPTIONS] PATTERN
Test what a pattern matches against cached extraction data.
Shows how many keys/values a pattern would match, with sample matches.
Requires cached extraction data — run 'pinman winreg extract --no-filter'
first if none exists.
Examples:
pinman winreg blacklist test "*\Classes\CLSID\*"
pinman winreg blacklist test "*LastChecked*" --type value
pinman winreg blacklist test "*\SolidWorks\*" --hive HKCU
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * PATTERN TEXT [required] │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --type [key|value] Pattern type (key or value). │
│ --hive [HKCU|HKLM|all] Which hive(s) to test against. │
│ --limit INTEGER Max matches to display. │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg clear-cache
Usage: pinman winreg clear-cache [OPTIONS]
Delete winreg pickle sidecars in the live extract directory.
Each `.reg`/`.hiv` file in `extract/winreg/` has a `.pkl` sidecar that caches
the parsed data so subsequent reads skip the parser. This deletes those
sidecars; the next read regenerates them.
Backup directories (`backup_NNN/winreg/`) are *not* touched — those sidecars
are backed up alongside their `.reg` files.
Use when forcing a fresh parse (e.g. after editing a source `.reg` without
bumping its mtime) or reclaiming disk space.
Examples:
pinman winreg clear-cache
pinman winreg clear-cache --force
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg diff
Usage: pinman winreg diff [OPTIONS] SOURCE [TARGET]
Compare winreg data between files or against live winreg.
SOURCE: Path to first .reg file
TARGET: Path to second .reg file (or omit if using --live)
Examples:
pinman winreg diff file1.reg file2.reg
pinman winreg diff backup.reg --live
pinman winreg diff old.reg new.reg -o json
pinman winreg diff old.reg new.reg -o json --file changes.json
┌─ Arguments ─────────────────────────────────────────────────────────────────┐
│ * SOURCE PATH [required] │
│ TARGET PATH │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --live Compare source file against │
│ live winreg. │
│ --hive [HKCU|HKLM|HKCR|HKU] Hive to compare when using │
│ --live (auto-detected if │
│ not specified). │
│ --values-only Only show value │
│ differences, not key │
│ differences. │
│ --file FILE Write the payload to this │
│ file as UTF-8 (default: │
│ stdout). │
│ --output -o [human|json] Output format (human | │
│ json). [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output │
│ incl. progress logs │
│ (applies to the whole run; │
│ default quiet — │
│ PINMAN_VERBOSE env var sets │
│ the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover
Usage: pinman winreg discover [OPTIONS] COMMAND [ARGS]...
Discover registry changes by comparing before/after extractions.
Default scope: HKCU\Software (where app settings live).
Use --hive and --root-key to adjust scope.
Workflow:
pinman winreg discover baseline # Before your change
<make your change — install, configure, etc.>
pinman winreg discover changes # See what changed
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. progress logs │
│ (applies to the whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ Discovery ─────────────────────────────────────────────────────────────────┐
│ baseline Take a baseline extraction before making changes. │
│ changes Show what changed since the last baseline. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover baseline
Usage: pinman winreg discover baseline [OPTIONS]
Take a baseline extraction before making changes.
Overwrites any existing baseline for this hive.
Examples:
pinman winreg discover baseline
pinman winreg discover baseline --root-key "Software\JoyToKey"
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM] Hive to extract (default: HKCU). │
│ --root-key TEXT Root key within hive (default: │
│ Software). │
│ --force -f Skip the confirmation prompt (and │
│ authorize the op when │
│ non-interactive). │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg discover changes
Usage: pinman winreg discover changes [OPTIONS] Show what changed since the last baseline. Examples: pinman winreg discover changes pinman winreg discover changes -o json ┌─ Options ───────────────────────────────────────────────────────────────────┐ │ --hive [HKCU|HKLM] Hive to compare (default: HKCU). │ │ --root-key TEXT Root key within hive (default: │ │ Software). │ │ --output -o [human|json] Output format (human | json). │ │ [default: human] │ │ --verbose/--quiet -v/-q Echo/hide detailed output incl. │ │ progress logs (applies to the whole │ │ run; default quiet — PINMAN_VERBOSE │ │ env var sets the default). │ │ --help -h,-? Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────┘
pinman winreg extract
Usage: pinman winreg extract [OPTIONS]
Extract winreg to .reg files.
By default, extracts full subtree dumps with blacklist filtering. Use
--tracked-only to extract only schema-tracked keys (fast, <1s).
With --from-file, filters an existing .reg file instead of extracting from
the live registry. Useful for post-processing raw dumps.
Destinations:
--out DIR write the .reg file(s) to a directory (default: extract
dir)
--out-file PATH write a single .reg file (single hive / --from-file)
Modes:
(default) Full extraction: dump allowed subtrees with blacklist
filtering
--tracked-only Fast: extract only schema-tracked keys via Python API
--no-filter No filtering - extract everything (raw)
Examples:
pinman winreg extract --hive HKCU
pinman winreg extract --hive all --out ./registry_backup
pinman winreg extract --tracked-only
pinman winreg extract --hive HKLM --no-filter
pinman winreg extract --from-file raw_dump.reg --out-file filtered.reg
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --hive [HKCU|HKLM|all] Winreg hive to extract (default: │
│ HKCU). Use 'all' for HKCU and │
│ HKLM. │
│ --out DIRECTORY Output DIRECTORY for the .reg │
│ file(s) (default: the extract │
│ dir). │
│ --out-file FILE Single output .reg file (single │
│ hive / --from-file only). │
│ --root-key TEXT Root key within hive to extract │
│ (e.g., Software/MyApp). │
│ --tracked-only Extract only schema-tracked keys │
│ (fast, <1s). Requires schema │
│ context. │
│ --no-filter Raw mode: skip all blacklist │
│ filtering (extract everything). │
│ --from-file FILE Filter an existing .reg file │
│ instead of extracting from live │
│ registry. │
│ --encoding [utf-8|utf-16] Output file encoding. │
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the │
│ whole run; default quiet — │
│ PINMAN_VERBOSE env var sets the │
│ default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg inventory
Usage: pinman winreg inventory [OPTIONS]
List winreg: entries from the schema and check if they exist on the system.
Shows which registry keys defined in your schema are present on the system
and which are missing from the current machine.
Examples:
pinman winreg inventory
pinman winreg inventory -o json
┌─ Options ───────────────────────────────────────────────────────────────────┐
│ --output -o [human|json] Output format (human | json). │
│ [default: human] │
│ --verbose/--quiet -v/-q Echo/hide detailed output incl. │
│ progress logs (applies to the whole │
│ run; default quiet — PINMAN_VERBOSE │
│ env var sets the default). │
│ --help -h,-? Show this message and exit. │
└─────────────────────────────────────────────────────────────────────────────┘
pinman winreg 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 "myapp" --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. │
└─────────────────────────────────────────────────────────────────────────────┘