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.
docker exec -it channelwatch python -m channelwatch.main --test-connectivityWhen 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:8089Status: ConnectedAPI version: OKA 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.
docker exec -it channelwatch python -m channelwatch.main --test-apiWhen 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.
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_CHANNEL_WATCHINGdocker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_VOD_WATCHINGdocker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_DISK_SPACEdocker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_RECORDING_EVENTSWhen 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:
| 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 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.
docker exec -it channelwatch python -m channelwatch.main --monitor-events 60Replace 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:
docker logs channelwatchdocker logs -f channelwatchThe -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.
Related pages
Section titled “Related pages”- 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