PinmanPinman
Menu

Technician Mode

Config

Configuration is stored in pinman_config.json in the app data directory (the active project home: pinman/data/hub/projects/<name>/ for dev/test, C:\ProgramData\Pinman\projects\<name>\ for prod). Each project home has its own config file.

Settings are read and written via:

  • CLI: pinman config get <key> / pinman config set <key> <value>
  • UI: the Config page (gear icon)

Managed settings#

A few settings are managed — they are bound to data outside the config file, so changing the value alone would orphan what it points at. config set and the Config page refuse them, and name the command that changes them safely instead. Today that is backups_root (owned by pinman capture move).

Backup Settings#

backups_root#

Type: string (absolute path) | Default: "" (unset)

Absolute path to the directory where pinman stores all backups. Must be set before any backup operations will work. Set during pinman project create; changed afterwards with pinman capture move --to <FULLPATH>, which relocates the archived files and rewrites the stored capture paths before updating this value. This is a managed setting — pinman config set backups_root ... is refused.

backup_interval#

Type: integer (minutes) | Default: 30

How often (in minutes) the auto-backup scheduler runs.

backup_workers#

Type: integer | Default: 1

Number of parallel threads used for file copies during a backup operation. 1 means serial (safe, slower). Tune with pinman capture maint workers --auto.

backup_capacity_low_multiplier#

Type: float | Default: 3.0

Threshold multiplier for low-disk-space warnings. If free space is less than N × full-backup-size, the capacity is classified as low.

busy_processes#

Type: list of strings | Default: []

Process names that indicate the machine is "in use" (e.g. vpinball.exe, futurepinball.exe, mame.exe on a pinball cabinet). Backup and other disruptive operations may be suppressed or warned when these are running.

Directory Settings#

directory_exclude_match#

Type: list of glob patterns | Default: []

Glob patterns matched against file and directory names during filesystem scans. Matching entries are skipped entirely. Example for a pinball cabinet: [".git", "*.log", "Cache", "_tmpDownload", "crash.*"].

Type: boolean | Default: true

Whether the filesystem scanner follows links — both symbolic links and Windows directory junctions — into their targets when recursing. Enabled by default so a relocated folder (e.g. VisualPinball\Tables linked to another drive) is scanned transparently. A per-directory follow_links schema property overrides this default for a specific directory's children.

directory_ignore_hidden_temporary#

Type: boolean | Default: true

When true, hidden files and directories (names starting with .) and Windows temporary files are excluded from scans.

File Settings#

file_calc_hash#

Type: boolean | Default: true

Whether to compute a content hash (SHA-256) for each file during scans. Hashes enable change detection and deduplication. Disable on large trees where hashing is too slow.

freshness_threshold#

Type: integer (seconds) | Default: 300

How many seconds before cached scan data is considered stale and needs a refresh.

max_file_cache#

Type: integer (MB) | Default: 512

Maximum total size of the in-memory adapter data cache. When the limit is reached, least-recently-used entries are evicted.

capture_max_items#

Type: integer | Default: 10000

Runaway brake on how many items a single capture scan may materialize before it stops descending (0 = unlimited). Guards against an accidental discovery capture over a whole drive. When the limit is hit, the capture still completes and warns; the un-scanned remainder is left in place, and re-capturing with a higher limit picks up where it left off.

Directory Paths#

reference_dir#

Type: string (relative or absolute path) | Default: "reference"

Path to the reference data directory (static lookup files such as property catalogs and blacklists). Relative paths are resolved from the app data directory.

profiles_dir#

Type: string (relative or absolute path) | Default: "profiles"

Path to the directory containing profile YAML files. Relative paths are resolved from the app data directory.

extract_dir#

Type: string (relative path) | Default: "extract"

Directory under app data where extracted .reg and .json files (winreg/winrt exports) are cached.

Registry Settings#

registry_binary_format#

Type: boolean | Default: false

When true, registry backups use the .hiv binary hive format instead of .reg text format. Requires administrator elevation; falls back to .reg if not elevated.

Logging Settings#

Each output sink has its own threshold. Valid values for both: DEBUG, DETAIL, INFO, WARNING, ERROR. DETAIL (between INFO and DEBUG) is detailed-but-routine progress (per-container scan steps, per-subtree extraction); DEBUG is dev-only per-item detail.

log_level#

Type: string | Default: "INFO"

Threshold for the log file (pinman.log). Set to DEBUG to capture per-item detail in the file (e.g. for a bug report).

progress_log_level#

Type: string | Default: "DETAIL"

Threshold for the in-memory job-progress stream that feeds the UI (capture/backup progress dialog + bar). DETAIL lets the UI show per-step progress; DEBUG per-item detail is excluded regardless, so the UI never floods.

Console/terminal output is not a config key. By default the terminal is quiet — only warnings and errors are echoed; regular output comes from the command itself. The --verbose flag (or PINMAN_VERBOSE) echoes detailed progress logs for a run; --debug (or PINMAN_DEBUG) echoes everything and lowers the file threshold to DEBUG. These are runtime flags / env vars, not config settings.

System / UI Settings#

service_watchlist#

Type: list of strings | Default: (see below)

Windows service names pinned to the top of the Services tab in the UI. Default includes Audio, Themes, Windows Search, Print Spooler, Superfetch, Diagnostics Tracking, Windows Update, and Windows Defender.

system_summary_props#

Type: object (category → list of property paths) | Default: (built-in)

Controls which system properties are shown at a glance in each OS category on the System tab. Keys are OS category names (e.g., "Display", "Power"); values are lists of property path strings using /-separated paths, with * as a wildcard for array items.