Skip to content

Reporting

Jump to bottom
Gil Burns edited this page Jun 7, 2026 · 4 revisions

Reporting

The patcherreport binary generates human-readable patch status reports from the data Patcher has collected. It reads the Discovered/ plists and LabelHistory/ files — it does not run any patching actions.

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

Reports can be run without sudo if you have read access to /Library/Application Support/Patcher/.

Subcommands

summary

Prints a one-line overview of the fleet's patch compliance status.

/usr/local/bin/tpp/patcherreport summary

Terminal output - summary

pending

Lists apps with staged updates waiting to be applied.

/usr/local/bin/tpp/patcherreport pending

Sample output:

Pending Updates (3)
──────────────────────────────────────────────────
  googlechrome       1.24.0 → 1.25.1   pending 3 days
  slack              4.38.0 → 4.39.2   pending 1 day
  zoom               6.2.0  → 6.3.0    pending 8 days  ⚠ focus deadline passed

recent

Lists apps successfully patched within the last N days (default: 7).

/usr/local/bin/tpp/patcherreport recent
/usr/local/bin/tpp/patcherreport recent --days 5

Terminal output - recent

broken

Lists labels that failed to resolve or consistently failed to download.

Terminal output - recent

/usr/local/bin/tpp/patcherreport broken

Labels appear here when:

  • The label file could not be evaluated.
  • Downloads failed more than StageDownloadFailThreshold consecutive times.
  • The label reported an unknown version and IgnoreUnknownVersionLabels is false.

Broken labels are retried when the effective labels version changes (i.e., when you update your Managed Labels Version.txt or when Installomator labels are updated).

never-updated

Lists apps that have been discovered and found to need an update, but have never had a successful apply.

/usr/local/bin/tpp/patcherreport never-updated

Sample output:

Never Updated (1)
──────────────────────────────────────────────────
  adobecreativeclouddesktop   discovered 2026-03-01, pending 49 days

label

Prints the full chronological event history for a single label: every discovery, update-found, stage, apply, deferral prompt outcome, and blocking-process interaction.

/usr/local/bin/tpp/patcherreport label claudedesktop

Terminal output - label

deferrals

Shows every dialog interaction recorded across all labels: deferral prompts, blocking-process outcomes, forced deadlines, and user-continue events. Sorted by most recent interaction. Accepts an optional --days filter.

This report is intended for administrators who need a verifiable record of what the user was shown and what action they took — for example, when a user claims they never saw a patching notification.

# All recorded dialog history
/usr/local/bin/tpp/patcherreport deferrals

# Only interactions from the last 14 days
/usr/local/bin/tpp/patcherreport deferrals --days 14

Terminal output - deferrals

Dialog event types recorded:

Event type Meaning
userContinued User clicked Continue on the deferral prompt
userDeferred User explicitly clicked Defer (detail shows duration chosen)
timedOutDeferred Deferral prompt timer expired; update auto-deferred
deadlineForced Hard deadline reached; update proceeded without user choice
blockingProcessNotified App was running; notification shown, update skipped
blockingProcessSkipped User clicked Skip Update on the blocking-process prompt
blockingProcessTimedOut Blocking-process prompt timer expired; process was killed, update proceeded
blockingProcessQuit User clicked Quit App; process was killed, update proceeded

Clone this wiki locally