Documentation
CLI Reference
watch - Add a Watcher

watch - Add a Watcher

The watch command adds a new update checker (watcher) to your configuration. Each watcher type corresponds to a package manager or update source. Some types accept additional flags to customize their behavior.

Usage

Terminal
update-watcher watch <type> [flags]

Where <type> is one of the 14 supported checker types listed below.

Watcher Types and Flags

Terminal
update-watcher watch apt [--security-only] [--no-sudo] [--hide-phased]
FlagDescription
--security-onlyOnly report security updates. Non-security updates are ignored.
--no-sudoDo not use sudo for apt-get update. Use when running as root.
--hide-phasedExclude phased rollout updates that your system cannot yet install. Enabled by default.
Terminal
update-watcher watch dnf [--security-only] [--no-sudo]
FlagDescription
--security-onlyOnly report security updates.
--no-sudoDo not use sudo for dnf check-update.
Terminal
update-watcher watch pacman [--no-sudo]
FlagDescription
--no-sudoDo not use sudo for pacman -Sy.
Terminal
update-watcher watch zypper [--security-only] [--no-sudo]
FlagDescription
--security-onlyOnly report security patches.
--no-sudoDo not use sudo for zypper commands.
Terminal
update-watcher watch apk [--no-sudo]
FlagDescription
--no-sudoDo not use sudo for apk update.
Terminal
update-watcher watch macos [--security-only]
FlagDescription
--security-onlyOnly report security updates from softwareupdate.
Terminal
update-watcher watch homebrew [--no-casks]
FlagDescription
--no-casksOnly check formulae. Skip cask (GUI application) updates.
Terminal
update-watcher watch snap
Terminal
update-watcher watch flatpak

No additional flags. These checkers report all available updates from Snap and Flatpak respectively.

Terminal
update-watcher watch docker

No additional flags. Checks all running Docker containers for newer image versions by comparing digests.

Terminal
update-watcher watch distro [--lts-only]
FlagDescription
--lts-onlyOnly notify about LTS (Long Term Support) releases. Ignores interim releases.
Terminal
update-watcher watch openclaw [--channel CHANNEL]
FlagDescription
--channel CHANNELRelease channel to monitor (e.g., stable, beta).
Terminal
update-watcher watch wordpress --path PATH [--name NAME] [--env TYPE]
FlagRequiredDescription
--path PATHYesAbsolute path to the WordPress installation directory.
--name NAMENoDisplay name for this WordPress site in notifications. Defaults to the directory name.
--env TYPENoPHP environment type (e.g., php, lando, ddev, docker). Controls how WP-CLI is invoked.
Terminal
update-watcher watch webproject --path PATH [--name NAME] [--env TYPE] [--managers LIST] [--no-audit]
FlagRequiredDescription
--path PATHYesAbsolute path to the project root directory.
--name NAMENoDisplay name for this project in notifications. Defaults to the directory name.
--env TYPENoEnvironment type that controls how package managers are invoked.
--managers LISTNoComma-separated list of package managers to check (e.g., npm,composer). Auto-detected if omitted.
--no-auditNoSkip security audit checks. Only report outdated packages.

Examples

Add an APT watcher with security-only filtering:

Terminal
update-watcher watch apt --security-only

Add a Docker watcher:

Terminal
update-watcher watch docker

Add a WordPress site with a custom name:

Terminal
update-watcher watch wordpress --path /var/www/mysite --name "Production Blog"

Add a web project monitoring npm and Composer:

Terminal
update-watcher watch webproject --path /var/www/app --managers npm,composer

Add a distro watcher that only reports LTS releases:

Terminal
update-watcher watch distro --lts-only

Multiple Instances

Most watcher types are singletons – you can only have one per type in your configuration. The exceptions are wordpress and webproject, which support multiple instances. Each instance is identified by its --path and optional --name.

To add a second WordPress site:

Terminal
update-watcher watch wordpress --path /var/www/site-a --name "Site A"
update-watcher watch wordpress --path /var/www/site-b --name "Site B"

To remove a specific instance, use the unwatch command with --name.

What Happens

When you run update-watcher watch, the command:

  1. Loads the existing configuration file (or creates one if none exists).
  2. Adds a new watcher entry with the specified type and options.
  3. Saves the updated configuration to disk.

The watcher is immediately available for the next update-watcher run invocation.

Related

  • unwatch – Remove a configured watcher.
  • Checkers – Detailed documentation for each checker type.
  • Configuration – Full YAML configuration reference.
  • setup – Interactive wizard for managing watchers.
setup - Interactive Setup Wizardunwatch - Remove a Watcher