run - Execute Update Checks
The run command is the primary entry point for Update-Watcher. It executes all configured update checkers, collects the results, and sends notifications through the configured channels. This is the command that cron jobs invoke on a schedule.
Usage
update-watcher run [flags]Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--format | text|json | text | Output format. Use json for machine-readable output suitable for scripting and pipelines. |
--only TYPE | string | (all) | Run only the specified checker type (e.g., apt, docker, wordpress). All other checkers are skipped. |
--notify BOOL | bool | (config) | Control notification delivery. true forces notifications regardless of send policy. false suppresses all notifications. Omit to follow the configured send_policy. |
--quiet | false | Suppress all output except errors. | |
--verbose | false | Enable verbose debug output. |
--notify flag overrides the send_policy setting in your configuration. When omitted, the configured policy applies (see Send Policy).Exit Codes
The run command uses exit codes to communicate results for scripting:
| Code | Meaning | Description |
|---|---|---|
| 0 | No updates | All checkers ran successfully and no updates were found. |
| 1 | Updates found | At least one checker reported available updates. |
| 2 | Partial failure | Some checkers succeeded, but at least one failed (e.g., network timeout, missing permissions). |
| 3 | Complete failure | All configured checkers failed. |
| 4 | Config error | The configuration file is missing, malformed, or contains invalid values. |
For detailed scripting examples using exit codes, see Exit Codes.
Examples
Basic Run
Execute all configured checkers and send notifications according to the configured send_policy:
update-watcher runJSON Output
Output results as JSON for parsing by other tools:
update-watcher run --format jsonCombine with jq to extract specific information:
update-watcher run --format json | jq '.checkers[] | select(.updates > 0)'For more JSON output examples, see JSON Output.
Run a Single Checker
Run only the APT checker, skipping all other configured checkers:
update-watcher run --only aptThis is useful for testing a specific checker or debugging issues with a single package manager.
Suppress Notifications
Run all checks but do not send any notifications. Results are printed to the terminal only:
update-watcher run --notify=falseThis is equivalent to a “dry run” and is useful for verifying that checkers are working before enabling notifications.
Force Notifications
Force notifications to be sent even if no updates are found, regardless of the configured send_policy:
update-watcher run --notify=trueThis is useful for testing notification delivery or as a heartbeat confirmation.
Quiet Mode for Cron
Run silently with no terminal output. Only errors are printed to stderr:
update-watcher run --quietThis is the mode used by the cron job created with update-watcher install-cron.
Verbose Debug Output
Enable detailed logging to diagnose issues:
update-watcher run --verboseThe verbose output shows each step: config loading, checker initialization, package manager queries, result parsing, and notification delivery.
Combining Flags
Run only the Docker checker with JSON output and no notifications:
update-watcher run --only docker --format json --notify=falseTypical Cron Entry
When scheduled via update-watcher install-cron, the cron entry looks like:
0 7 * * * /usr/local/bin/update-watcher run --quietFor dedicated service user setups:
0 7 * * * /usr/local/bin/update-watcher run --quiet --as-service-userRelated
- JSON Output – Detailed guide to parsing JSON results.
- Exit Codes – Scripting reference for all exit codes.
- Send Policy – Control when notifications are sent.
- Cron Scheduling – Automate update checks on a schedule.