CLI Commands

The ChannelWatch web UI covers most diagnostic needs through the Diagnostics tab. These CLI commands exist for situations where the web UI is unavailable, you’re running headless, or you want to script a health check.

Before you start

All commands on this page run inside the container with docker exec, so the channelwatch container must already be running. If the container is stopped or crashing, fix that first from Common Issues.

Test connectivity

Checks the first enabled DVR’s /status endpoint and event-stream subscription endpoint.

docker exec -it channelwatch python -m core.main --test-connectivity

When to use it: Run this first when notifications stop arriving. If connectivity fails, the problem is network or DVR configuration, not the notification provider.

Expected output: The diagnostic logs the target, server version, and event-stream check. A passing result follows this shape (the version and log prefixes vary):

🔧 ── Connectivity Test ──
Connecting to 192.168.1.100:8089...
Server version: <version>
Testing event stream...
✅ [PASS]  Server and event stream reachable

A passing test exits with status 0. An HTTP failure or connection exception prints a FAIL result and exits with status 1.

Test API endpoints

Exercises the Channels DVR API endpoints that ChannelWatch depends on for alert data.

docker exec -it channelwatch python -m core.main --test-api

When to use it: Run this after --test-connectivity passes but alerts are still missing. It confirms that the specific API calls ChannelWatch makes are returning valid data, not just that the server is reachable.

Expected output: The command groups six checks under Core System, Channel & Program Data, and Recording & VOD Data. Each endpoint prints PASS (HTTP 200) or FAIL, followed by a passed/failed count. It exits with status 0 only when all six endpoints return HTTP 200; otherwise it exits with status 1.

Test individual alert types

Sends a simulated test notification for a specific alert type through your configured notification providers.

docker exec -it channelwatch python -m core.main --test-alert ALERT_CHANNEL_WATCHING
docker exec -it channelwatch python -m core.main --test-alert ALERT_VOD_WATCHING
docker exec -it channelwatch python -m core.main --test-alert ALERT_DISK_SPACE
docker exec -it channelwatch python -m core.main --test-alert ALERT_RECORDING_EVENTS

When to use it: Use these to confirm that a specific alert type is wired up correctly end-to-end, from ChannelWatch through to your notification provider. Useful after changing provider credentials or enabling a new alert type.

Expected output: A successful dispatch prints a PASS result and exits with status 0. A missing provider, unregistered alert, or failed dispatch prints FAIL and exits with status 1. Disk space test alerts include [TEST] in the notification title. ALERT_RECORDING_EVENTS runs five tests in sequence: scheduled, started, completed, stopped, and cancelled.

Alert type reference:

Argument	Alert type
`ALERT_CHANNEL_WATCHING`	Live TV viewing notification
`ALERT_VOD_WATCHING`	Recorded content playback notification
`ALERT_DISK_SPACE`	Disk space warning or critical notification
`ALERT_RECORDING_EVENTS`	Recording lifecycle and outcome notification

Monitor event stream

Connects to the Channels DVR event stream and prints raw events for a specified number of seconds, then exits.

docker exec -it channelwatch python -m core.main --monitor-events 60

Replace 60 with a positive whole number of seconds. The command waits for that monitoring window, then stops the stream and exits.

When to use it: Use this to confirm that ChannelWatch can connect to the first enabled DVR’s event stream and inspect any raw lines received during the window. If you trigger DVR activity and see no matching event lines, repeat the check and inspect the DVR connection and logs.

Expected output: After a successful HTTP connection, each non-empty server-sent-event line is logged as Event: <line>. An idle stream can receive zero lines and still pass because the connection itself succeeded. The final count reports how many non-empty lines were received.

🔧 ── Event Stream Monitor (60s) ──
Monitoring events for 60 seconds
Connecting to event stream...
Connected to event stream
Monitoring complete - 0 events received
✅ [PASS]  Stream monitored

The command exits with status 0 when the event-stream connection succeeds, even if it receives no event lines. If the connection fails, it still waits for the requested monitoring window, prints a failed result, and exits with status 1.

Scripting health checks

For a simple scripted check, run connectivity first and only continue to API tests if the first command succeeds:

if docker exec channelwatch python -m core.main --test-connectivity; then
  docker exec channelwatch python -m core.main --test-api
else
  echo "Connectivity test failed, skipping API checks" >&2
  exit 1
fi

This works in cron, a lightweight CI job, or a remote admin script because both diagnostics return 0 on success and 1 on a diagnostic failure. Keep the event-stream monitor out of quick health checks because it always waits for the requested duration; receiving zero event lines does not make it fail after a successful connection.

Checking container logs

For general troubleshooting, container logs are often the fastest path to an answer:

docker logs channelwatch
docker logs -f channelwatch

The -f flag follows the log in real time. ChannelWatch logs connection events, alert triggers, notification sends, and any errors. If you’re not sure where to start, check the logs first.

Common Issues - solutions for the most frequent problems
Diagnostics - using the web UI diagnostic panel
Notification Examples - what each alert type looks like when delivered