Skip to content
ChannelWatch

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.

All commands run inside the container using docker exec. Your container must be running before any of these work.

Test connectivity

Section titled “Test connectivity”

Verifies that ChannelWatch can reach your Channels DVR server and authenticate against its API.

Terminal window
docker exec -it channelwatch python -m channelwatch.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: A short report showing the DVR host, port, and whether the connection succeeded. A passing result looks like:

Testing connectivity to Channels DVR...
Host: 192.168.1.100:8089
Status: Connected
API version: OK

A failing result shows the specific error (connection refused, timeout, or authentication failure) so you know where to look next.

Test API endpoints

Section titled “Test API endpoints”

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

Terminal window
docker exec -it channelwatch python -m channelwatch.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: A list of endpoints tested with pass/fail status for each. All endpoints should show OK. A failure on a specific endpoint points to a DVR version mismatch or a permissions issue on that route.

Test individual alert types

Section titled “Test individual alert types”

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

Terminal window
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_CHANNEL_WATCHING
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_VOD_WATCHING
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_DISK_SPACE
docker exec -it channelwatch python -m channelwatch.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 confirmation that the test payload was sent, followed by the notification arriving on your device. Disk space test alerts are labeled [TEST] in the notification title so they’re easy to distinguish from real alerts.

Alert type reference:

ArgumentAlert type
ALERT_CHANNEL_WATCHINGLive TV viewing notification
ALERT_VOD_WATCHINGRecorded content playback notification
ALERT_DISK_SPACEDisk space warning or critical notification
ALERT_RECORDING_EVENTSRecording lifecycle notification (scheduled, started, completed, cancelled)

Monitor event stream

Section titled “Monitor event stream”

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

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

Replace 60 with any number of seconds. The command exits cleanly after the timer expires.

When to use it: Use this to confirm that the Channels DVR event stream is active and delivering events. If you start watching a channel and no events appear during the monitoring window, the event stream connection is broken or the DVR is not emitting events for that activity.

Expected output: Raw event objects printed to stdout as they arrive. A healthy stream shows events when DVR activity occurs. An idle DVR produces no output, which is normal if nothing is playing.

Monitoring event stream for 60 seconds...
[12:34:01] Event: channel.watching.start {"channel": "ABC", "device": "Living Room", ...}
[12:34:45] Event: channel.watching.stop {"channel": "ABC", "device": "Living Room", ...}
Monitoring complete.

If the stream connection fails, the command prints the error and exits immediately rather than waiting for the full duration.

Checking container logs

Section titled “Checking container logs”

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

Terminal window
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.

Section titled “Related pages”