urlwatch - Man Page

Monitor webpages and command output for changes


urlwatch [options] [JOB ...]


urlwatch is intended to help you watch changes in webpages and get notified (via e-mail, in your terminal or through various third party services) of any changes. The change notification will include the URL that has changed and a unified diff of what has changed.

See urlwatch-intro(7) for a quick start guide and tutorial, and urlwatch-cookbook(7) for usage recipes and tricks.

This manpage describes the CLI tool.

positional arguments:

index of job(s) to run, as numbered according to the --list command. If none are specified, then all jobs will be run.

optional arguments:
-h, --help

show this help message and exit


show program's version number and exit

-v, --verbose

show debug output

files and directories:
--urls FILE

read job list (URLs) from FILE

--config FILE

read configuration from FILE

--hooks FILE

use FILE as hooks.py module

--cache FILE

use FILE as cache database


Enter password for SMTP (store in keyring)


Enter password for XMPP (store in keyring)


List telegram chats the bot is joined to

--test-reporter REPORTER

Send a test notification

job list management:

list jobs

--add JOB

add job (key1=value1,key2=value2,...)

--delete JOB

delete job by location or index

--change_location JOB NEW_LOCATION

change the location of an existing job by location or index

--test-filter JOB

test filter output of job by location or index

--test-diff-filter JOB

test diff filter output of job by location or index (needs at least 2 snapshots)

--dump-history JOB

dump historical cached data for a job

interactive commands ($EDITOR/$VISUAL):

edit URL/job list


edit configuration file


edit hooks script


list supported jobs/filters/reporters

--gc-cache RETAIN_LIMIT

remove old cache entries, keeping the latest RETAIN_LIMIT (default: 1)



Configured job and filter list, see urlwatch-jobs(5) and urlwatch-filters(5)


Global and reporter settings, see urlwatch-config(5) and urlwatch-reporters(5)


A Python 3 module that can implement new job types, filters and reporters


A SQLite 3 database (minidb) that contains the state history of jobs (for diffing)

See Also

urlwatch-intro(7), urlwatch-cookbook(7), urlwatch-deprecated(7), urlwatch-jobs(5), urlwatch-filters(5), urlwatch-config(5), urlwatch-reporters(5)


Thomas Perl <https://thp.io/>

Bug Tracker




Referenced By

urlwatch-config(5), urlwatch-cookbook(7), urlwatch-filters(5), urlwatch-intro(7), urlwatch-jobs(5), urlwatch-reporters(5).

May 03, 2023 urlwatch 2.28 Documentation