watch_list
Uptime RobotDefine Uptime Robot monitors as code in a Robotfile
- Manages
- Uptime Robot monitors
- Language
- Ruby
- Package
- watch_list
- CLI
- watch_list
- Config file
- Robotfile
monitor "http monitor" do
target "http://example.com"
interval 5
paused false
alert_contact :email, "[email protected]"
type :http
end
monitor "keyword monitor" do
target "http://example.com"
interval 5
paused false
alert_contact :email, "[email protected]"
type :keyword do
keywordtype :exists
keywordvalue "Example Domain"
end
endwatch_list is a Ruby command-line tool that manages Uptime Robot monitors as code. You export existing HTTP, keyword, ping, and port checks into a Robotfile, review edits in Git, then apply them idempotently. A dry-run previews every monitor it would create, update, or delete.
What is watch_list?
watch_list is a command-line tool that manages Uptime Robot monitors as code. Instead of clicking through the Uptime Robot dashboard to build checks, you declare them in a Ruby file. This file is called a Robotfile. watch_list then creates, updates, or removes monitors to match. Auth is a single WATCH_LIST_API_KEY variable.
Uptime checks are easy to forget. You set them once and rarely look again. When a service is renamed or retired, its monitor often lives on. It pages nobody, or pages the wrong people. Monitors as code fixes that:
- The Robotfile sits with your other codenized configuration.
- A new service adds its checks in the same pull request that ships it.
- A dry-run shows drift between the file and the account.
watch_list suits small teams standardized on Uptime Robot who want reviewable monitoring. If your alerts live in Datadog instead, Barkdog applies the same idea there.
- Manages Uptime Robot monitors (HTTP, keyword, ping, and port) as code.
- Config lives in a file named the Robotfile, kept in Git.
- Can encrypt secrets like basic-auth passwords so they commit safely.
- A dry-run shows drift, and applies are idempotent.
- For Datadog alerts, its sibling Barkdog uses the same pattern.
- The repository is archived and dormant since 2016; verify API compatibility.
Install and run watch_list
Install
Install the watch_list gem (Ruby required).
$ gem install watch_listExport current state
Pull the live Uptime Robot configuration into a Robotfile.
$ watch_list -e -o RobotfileDry-run, then apply
Preview the diff, then apply the change for real.
$ watch_list -a --dry-runwatch_list uses the classic export, review, apply loop. With WATCH_LIST_API_KEY set, run watch_list -e to export every monitor in the account into the DSL, then commit the file. That first export is worth a careful read. Stale monitors from long-dead services tend to surface right away.
To add or change a check, edit the Robotfile and run watch_list -a --dry-run. The dry-run compares the file to the live account. It lists the monitors it would create, update, or delete, with no state-changing API calls. When the plan matches the pull request, run watch_list -a. Applies are idempotent, so the same command is safe in CI. A periodic dry-run doubles as drift detection for monitors edited by hand in the UI.
Run your first export and read it top to bottom before changing anything. Old accounts almost always hide monitors for services that no longer exist.
What watch_list can do
Four monitor types
The DSL covers Uptime Robot's core checks: <code>:http</code>, <code>:keyword</code> (with <code>keywordtype</code> and <code>keywordvalue</code>), <code>:ping</code>, and <code>:port</code>.
Alert contacts in the DSL
<code>alert_contact</code> attaches notification targets like email addresses to a monitor. Standalone <code>alert_contact</code> blocks define the contacts themselves.
Idempotent apply with dry-run
<code>watch_list -a</code> makes the account match the Robotfile. The dry-run prints the plan without calling the API, and re-applying an unchanged file does nothing.
Built-in secret encryption
<code>watch_list --encrypt</code> turns values like basic-auth passwords into ciphertext you can commit. It is keyed by <code>watch-list.pass</code> and <code>watch-list.salt</code>, and decrypts on apply.
Export and split
<code>watch_list -e</code> dumps every monitor into the DSL. Add <code>--split</code> to write them across several files for larger accounts.
Status from the terminal
<code>watch_list -s</code> reports current monitor status. It is handy for a quick check without opening the dashboard.
| Type | What it checks |
|---|---|
:http | A URL returns a healthy response |
:keyword | A page contains (or lacks) a given word |
:ping | A host answers a network ping |
:port | A specific TCP port is open |
When teams reach for watch_list
Monitors shipped with the service
Add the HTTP and keyword checks for a new endpoint in the same pull request that adds it. The monitor gets reviewed with the code it watches. Nothing waits on someone clicking through the dashboard.
Cleaning up a crowded account
Export the full account to a Robotfile and read it like an inventory. Deleting a stale monitor is a one-line diff, checked by dry-run, not a risky bulk edit in the UI.
Committing checks that need credentials
Monitors on basic-auth endpoints need a username and password. The <code>--encrypt</code> workflow keeps those secrets as ciphertext in Git, and watch_list decrypts them at apply time.