Promethist Watchdog

Command line

Watchdog can be driven from a terminal - locally, or over SSH from another machine. Commands talk to the Watchdog already running on that PC. Changes made from the terminal appear in its window immediately, and vice versa.

Use wdog.exe, in the install folder:

"C:\Program Files\Promethist Watchdog\wdog.exe" status

Add that folder to PATH to use just wdog status. The rest of this page writes it that way.

Use wdog.exe, not PromethistWatchdog.exe.

The tray program is a windowed application, and PowerShell does not reliably wait for one: $out = & PromethistWatchdog.exe status comes back empty, … > file writes nothing, and a command that fails reports success. wdog.exe is a console program built from the same code, so output and exit codes behave.

Seeing what is happening

wdog status                  every app, live
wdog status kiosk-shell      just one
wdog status --wide           add the GPU and VRAM columns
wdog list                    what is configured, including disabled apps
wdog version                 the version, and whether Watchdog is running

status shows what is running now; list shows what is configured. Disabled apps appear in list, and in status as disabled.

NAME                STATE            PID PROCS   CPU%   RAM MB  UPTIME RESTARTS
kiosk-shell         running         7312     4   12.5    843.2  3h 12m        0
signage-player      backoff            -     0      -        -       -        2
batch-importer      circuit_open       -     0      -        -       -        3

3 apps: 1 running, 1 restarting, 1 gave up

Starting and stopping

wdog start kiosk-shell
wdog stop kiosk-shell
wdog restart kiosk-shell
wdog restart --all

stop and restart wait for the app to shut down gracefully, taking up to its grace period (20 seconds by default), so they are not instant. If a command takes longer than the timeout, Watchdog keeps going - the message says so, and wdog status shows the result.

Reading logs

wdog logs kiosk-shell                      the app's last 50 lines of output
wdog logs kiosk-shell --file events        why it last restarted
wdog logs kiosk-shell --file err -n 200
wdog logs                                  Watchdog's own log
wdog logs kiosk-shell -f                   keep printing new lines
wdog logs kiosk-shell --path               just print the path

Use --file events when an app keeps restarting: it records every launch, exit, freeze verdict and restart decision.

Logs live in per-day folders. Left running overnight, -f automatically follows the new day’s file and announces the switch.

Changing settings

Settings are addressed by their name in watchdog.yaml, with . between levels:

wdog config set log_retention_days 14
wdog config set daily_reboot.time 04:15
wdog app set kiosk-shell autostart true
wdog app set kiosk-shell launch.executable "C:\Kiosk\kiosk.exe"
wdog app set kiosk-shell freeze_detection.gui_hang.consecutive_hung_polls 12

You do not have to remember the names - ask:

wdog app get kiosk-shell --paths      every setting of that app, with its value
wdog config get --paths               every global setting
wdog app show kiosk-shell             the whole app as it is stored

List values take one argument each, after a --:

wdog app set kiosk-shell launch.args -- --profile prod --port 8080

The -- matters: without it, --profile looks like a command-line option. Quiet windows and environment variables use ; between entries:

wdog app set kiosk-shell quiet_windows "Mon,Tue 22:00-06:00;all 02:00-03:00"
wdog app set kiosk-shell launch.env "PROFILE=prod;REGION=eu"

Changing a setting restarts that app so the change takes effect, which the command confirms. Add --no-restart to save changes while leaving the app running on its old settings. A few global settings only take effect the next time Watchdog itself starts (the health poll interval, the log folder); those say so too.

wdog app reset <app> <setting> restores a setting to its default.

Adding and removing apps

wdog app add kiosk --exe "C:\Kiosk\kiosk.exe" --arg=--kiosk --visibility on_top
wdog app add kiosk --exe "C:\Kiosk\kiosk.exe" --start
wdog app remove kiosk
wdog app move kiosk --to 1        change the start and recycle order
wdog app add signalling --url https://signalling.example.com/

For an argument starting with a dash, use the attached form (--arg=--kiosk); repeat --arg for more. For long lists, it is easier to add the app first, then use app set … launch.args — ….

--url adds a web address to check instead of a program; see Watching a server by its web address.

Backup and restore

wdog config export                       writes a dated file into the current folder
wdog config export C:\backup\wd.yaml
wdog config import C:\backup\wd.yaml --replace
wdog config import C:\backup\wd.yaml --merge

--replace stops and removes existing apps first, then loads the file’s apps and global settings. --merge keeps existing apps, adding only those whose names are not already present. One of the two is required, as they are destructive in different ways.

The SMTP password is never exported. Set it on the new machine with:

"my-password" | wdog config smtp-password --stdin

It is purposely read from standard input so it never appears in a command line or your shell history.

Stopping Watchdog itself

wdog quit --yes

This stops Watchdog and every app it supervises. To start it again on a remote machine, run its logon task:

schtasks /run /tn PromethistWatchdog

Powering the PC off

wdog shutdown --in 60 --reason "UPS on battery" --yes
wdog shutdown --cancel
wdog shutdown --status
wdog shutdown --dry-run

Stops every app tidily, then powers the machine off — for a kiosk on a UPS, driven by whatever is watching the mains. It returns as soon as the countdown starts, so it never blocks a UPS agent; the stopping happens on its own.

No new exit codes: a delay longer than the configured maximum exits 5 (bad value), and a cancel that arrives too late exits 3 (conflict).

See Shutting down when the power fails for how to choose the delay and how to let a building system trigger it over the network.

Checking the internet connection

wdog network                     today's checks, summarised
wdog network --day 2026-08-04    an earlier day
wdog network --test              measure right now, and print it
wdog network --path              print the path of today's file

--test runs a full measurement, so it takes a few seconds and moves real data. Run it once when commissioning a machine: it is the check that proves the measurement works there before you rely on a year of files.

See Proving the network was the problem.

Status reports to a monitoring server

wdog heartbeat                     what is being reported, and how the last round went
wdog heartbeat --test              send one round now, and print each answer
wdog heartbeat --dry-run           print the JSON that would be sent, and send nothing
"the-key" | wdog config heartbeat-key --stdin

Both --test and --dry-run work while status reports are switched off, so the address, key and format can be checked before the schedule starts. The key is read from standard input for the same reason as the SMTP password.

See Reporting status to a monitoring server.

Scripting it

Every command takes --json, which prints one JSON document and nothing else:

$s = wdog --json status | ConvertFrom-Json
$s.data.apps | Where-Object state -ne 'running' | ForEach-Object { $_.name }

# Restart anything that has given up
wdog --json status | ConvertFrom-Json |
  ForEach-Object { $_.data.apps } |
  Where-Object state -eq 'circuit_open' |
  ForEach-Object { wdog restart $_.name }

Failures are also JSON, leaving nothing else to parse:

{
  "ok": false,
  "command": "restart",
  "data": null,
  "error": { "kind": "app_not_found", "message": "no app named 'kiosk'" },
  "exit_code": 3,
  "schema": 1
}

exit_code appears inside the document alongside the process exit code, because $LASTEXITCODE is easily lost in a pipeline.

Exit codes

Code	Meaning
0	Success. Note that `status` exits 0 even when apps are unhealthy - health is in the output, not the exit code.
1	Tried and failed (the app would not launch, the file could not be written).
2	Bad command line, unknown setting name, or a value that does not fit.
3	No such app, or no such log file.
4	Watchdog is not running, or cannot be reached.
5	Cannot be done in this state (a duplicate app name, or a confirmation was needed).
6	The command was accepted but did not finish in time. It is still running.

Over SSH

Nothing special is needed - commands work the same way through Windows OpenSSH:

ssh kiosk-pc "wdog status --json"
ssh kiosk-pc "wdog restart kiosk-shell"

Two rules:

Log in as the same Windows user that Watchdog runs as. The control channel is restricted to that account (and to administrators). A different account gets a clear "running under a different Windows account" message.
Elevation does not matter. A non-elevated session can control an elevated Watchdog, which is typical since its logon task runs with the highest available privileges.

Turning the control channel off

Add this to watchdog.yaml under global: and restart Watchdog:

global:
  control:
    enabled: false

Commands will then report that Watchdog is not accepting them. Setting the WATCHDOG_NO_CONTROL environment variable does the same thing, which is useful when debugging the configuration itself.