Skip to content

Command Line Reference

Jump to bottom
Gil Burns edited this page Apr 22, 2026 · 3 revisions

Command-Line Reference

Three binaries are installed to /usr/local/bin/tpp/. All require root (sudo) except where noted.

patcher

The core patching engine. Each subcommand runs one phase of the patching workflow.

sudo /usr/local/bin/tpp/patcher <subcommand> [options]

Subcommands

scan

Discovers installed third-party applications and writes per-app metadata to Discovered/.

sudo /usr/local/bin/tpp/patcher scan

Reads all label files (Installomator + Managed Labels), evaluates each label to detect installed apps, and records the installed version and app paths. Runs a full scan unconditionally regardless of the configured ScanIntervalDays interval.

check

Checks all discovered apps for available updates.

sudo /usr/local/bin/tpp/patcher check

Evaluates each Discovered plist against the label's version logic. Marks apps as needing an update when the available version differs from the installed version. Apps with unresolvable versions are handled according to IgnoreUnknownVersionLabels.

stage

Downloads and validates installers for apps that need updating.

sudo /usr/local/bin/tpp/patcher stage

Downloads to a temporary staging area, verifies the Team ID signature, and holds the installer ready for apply. Skips apps that are already staged at the current version.

stageOnDemand

Like stage, but forces a fresh download even if an installer is already staged. Useful for testing or recovering from a corrupted download.

sudo /usr/local/bin/tpp/patcher stageOnDemand

apply

Installs all staged updates.

sudo /usr/local/bin/tpp/patcher apply

Runs the Installomator label for each app with a staged update. Prompts the user via swiftDialog if blocking processes are running (when SwiftDialogEnabled is true). Respects deferral state and deadlines.

ensure

Ensures swiftDialog is installed and up to date.

sudo /usr/local/bin/tpp/patcher ensure

Checks whether swiftDialog is present at /usr/local/bin/dialog. If missing or outdated, installs it via Installomator. Safe to run in a postinstall script or as a recurring policy.

resetHistory

Clears per-label patch history, allowing labels to be re-evaluated from scratch.

# Reset all labels
sudo /usr/local/bin/tpp/patcher resetHistory

# Reset a single label
sudo /usr/local/bin/tpp/patcher resetHistory googlechrome

Removes LabelHistory/<label>.json files. After a reset, the next apply cycle treats the label as if it has never been patched, resetting deferral counts and deadline tracking.

Use case: After manually installing a new version of an app, run resetHistory <label> so the scheduler doesn't attempt to re-apply an older staged installer.

patcherscheduler

The daemon entrypoint. In normal operation it is invoked by the LaunchDaemon, not by an administrator directly. It evaluates all four phase intervals and runs any that are due.

sudo /usr/local/bin/tpp/patcherscheduler

To trigger an immediate run, use launchctl kickstart:

sudo launchctl kickstart system/com.gilburns.patcher.scheduler

status

Prints the current patching schedule — last run time, interval, and next scheduled run for each phase — without modifying any state. Does not require the daemon to be running.

# Human-readable table (default)
/usr/local/bin/tpp/patcherscheduler status

# JSON output
/usr/local/bin/tpp/patcherscheduler status --json

# Plist (XML) output
/usr/local/bin/tpp/patcherscheduler status --plist

The table output shows each phase with its configured interval, the last time it ran, and when it is next due. It also reports the effective labels version, any pending label updates that would trigger an early scan, and the initial deployment delay status (if configured).

The --json and --plist formats are suitable for ingestion by monitoring tools or MDM scripts.

status does not require sudo — it only reads scheduler state and preferences.

patcherreport

Generates human-readable patch status reports. Does not require root when reporting on data already written by the daemon.

/usr/local/bin/tpp/patcherreport <subcommand>

See Reporting for full details on each subcommand's output format.

Subcommands at a Glance

Subcommand Description
summary Overall patching statistics
pending Apps staged but not yet applied
recent [--days N] Labels with activity in the last N days (default: 30)
broken Labels that failed to resolve or download
never-updated Apps discovered but never successfully patched
label <name> Full chronological event history for a single label
deferrals [--days N] Dialog interaction history: deferrals, blocking-process outcomes

See Reporting for full output examples and format options (--json, --csv, --output).

Clone this wiki locally