Reporting

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

Sample output:

Patcher Summary — 2026-04-19
  Managed apps:    42
  Up to date:      38
  Pending update:   3
  Never updated:    1
  Broken labels:    0

---

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 30

Sample output:

Recently Patched (last 7 days)
──────────────────────────────────────────────────
  microsoftword      16.83 → 16.84   applied 2026-04-17
  firefox            125.0 → 125.0.1  applied 2026-04-15

---

broken

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

/usr/local/bin/tpp/patcherreport broken

Sample output:

Broken Labels (1)
──────────────────────────────────────────────────
  myinternalapp    failed to resolve label (last checked: 2026-04-18)

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 googlechrome

Sample output:

════════════════════════════════════════════════════════════════════════════════
 History: googlechrome
 First discovered: 2026-03-01  v124.0.6367.60
 Total events: 7
════════════════════════════════════════════════════════════════════════════════
 Date              Event                    Details
────────────────────────────────────────────────────────────────────────────────
 2026-03-01 08:14  discovered               installed v124.0.6367.60
 2026-04-02 08:10  updateFound              124.0.6367.60 → 125.0.6422.78
 2026-04-02 08:11  staged                   v125.0.6422.78  89.3 MB
 2026-04-15 09:00  userDeferred             deferred 1 hr
 2026-04-15 10:05  timedOutDeferred         auto-deferred 30 min (timer expired)
 2026-04-16 08:30  deadlineForced           proceeded — hard deadline reached
 2026-04-16 08:31  applied                  124.0.6367.60 → 125.0.6422.78
════════════════════════════════════════════════════════════════════════════════

---

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

Sample output:

════════════════════════════════════════════════════════════════════════════════
 Dialog Interactions Report  —  2026-04-19 14:30
════════════════════════════════════════════════════════════════════════════════
 3 label(s)  ·  4 deferral(s)  ·  1 deadline(s) forced

 zoom  (1 deferral · deadline forced)
 ───────────────────────────────────────────────────────────────────────────────
  2026-04-18 09:00  userDeferred             deferred 1 hr
  2026-04-19 08:00  deadlineForced           proceeded — hard deadline reached

 googlechrome  (2 deferrals)
 ───────────────────────────────────────────────────────────────────────────────
  2026-04-15 09:00  userDeferred             deferred 2 hrs
  2026-04-15 11:05  timedOutDeferred         auto-deferred 30 min (timer expired)
  2026-04-16 08:30  userContinued            user clicked Continue

 firefox
 ───────────────────────────────────────────────────────────────────────────────
  2026-04-17 11:30  blockingProcessSkipped   user clicked Skip Update — firefox
  2026-04-17 14:00  blockingProcessQuit      user clicked Quit App — firefox

════════════════════════════════════════════════════════════════════════════════

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