Usage#
The main entry point for the Patcher CLI (patcherctl).
Added in version 2.0
Patcher has been split into three separate commands; Analyze, Export, and Reset
Viewing Help#
Patcher accepts both --help
and -h
parameters to view the help menu. Additionally, help is available for each subcommand and can be viewed by executing patcherctl <command> --help
.
$ patcherctl --help
Option |
Description |
---|---|
|
Show the version and exit. |
|
Enable debug logging (verbose mode). |
|
Show this message and exit. |
Exit Codes#
Patcher leverages specific exit codes depending on what type of error occurred at runtime:
Exit Code |
Description |
---|---|
0 |
Success |
1 |
Handled exception (e.g., PatcherError or user-facing issue) |
2 |
Unhandled exception |
4 |
API error (e.g., unauthorized, invalid response) |
130 |
KeyboardInterrupt (Ctrl+C) |
Debug Mode (verbose)#
Patcher accepts a global --debug
(or -x
) flag to show debug log level messages and higher to standard out. This overrides the built in Animation
from showing so no message conflicts occur. This flag is handled at the root CLI level and thus can be passed to any command.
$ patcherctl export --path '/path/to/save' --pdf --debug
Would result in a similar output as:
DEBUG: Checking bearer token validity
DEBUG: Bearer token passed validity checks.
DEBUG: Verifying token lifetime is greater than 5 minutes
DEBUG: Token lifetime verified successfully.
DEBUG: Beginning Patcher process...
DEBUG: Validating path provided is not a file...
DEBUG: Output path '/path/to/save' is valid.
DEBUG: Attempting to create directories if they do not already exist...
DEBUG: Reports directory created at '/path/to/save'.
DEBUG: Attempting to retrieve policy IDs.
DEBUG: Retrieved policy IDs for X policies.
DEBUG: Attempting to retrieve patch summaries.
DEBUG: Received policy summaries for X policies.
DEBUG: Generating excel file...
DEBUG: Excel file generated successfully at '/path/to/save/Patch-Reports/patch-report-07-05-24.xlsx'.
DEBUG: Patcher finished as expected. Additional logs can be found at '~/Library/Application Support/Patcher/logs'.
DEBUG: 41 patch reports saved successfully to /path/to/save/Patch-Reports.
Command Dependencies#
The analyze command is tightly integrated with the export command. It is important to understand this dependency for using Patcher effectively.
Key Points#
Export Command Requirement: The
export
command caches patch report data for later use by theanalyze
command, ensuring the data is available for analysis without having to run multiple export commands.Alternative Input: The
analyze
command can accept patch reports via the--excel-file
option, but these files must adhere to the schema of an exported patch report to prevent errors. Refer to the exported report structure for details.
Example Workflow#
$ patcherctl export --path /path/to/save
$ patcherctl analyze --criteria most-installed --threshold 75
$ patcherctl analyze --excel-file /path/to/patch-report.xlsx --criteria least-installed
Note
If no objects meet the specified criteria during analysis, a warning will be displayed:
$ patcherctl analyze --criteria below-threshold
⚠️ No PatchTitle objects meet criteria FilterCriteria.BELOW_THRESHOLD
Avoiding Errors#
Verify that exported patch reports are up-to-date before running the
analyze
command.Double-check that manually provided files conform to the patch report schema to avoid processing errors.
Data Caching#
Starting with version 2.0, Patcher now leverages data caching to improve performance and provide efficient handling of patch data. The cached data is stored in the user library cache directory (~/Library/Caches/Patcher
).
Caching Behavior#
Enabled by Default: Cached data is stored as pickle files (
*.pkl
) for quick reuse.Automatic Cleaning: Cache files older than 90 days are automatically removed to save disk space.
Disabling Caching: Caching can be disabled at any time by passing the
--disable-cache
flag with any command at runtime.
Managing Cached Data#
The following commands are available to assist in managing cache data:
$ open ~/Library/Caches/Patcher
reset
command.#$ patcherctl reset cache
✅ Reset finished successfully.
--disable-cache
flag to any command to temporarily disable caching.#$ patcherctl export --path /path/to/save --disable-cache
Automatic Cache Cleaning#
Cache files older than 90 days are automatically cleaned each time data is cached or retrieved. This is designed to ensure efficient use of disk space while providing an ample time range for trend analysis.