Skip to content
ChannelWatch

doctor CLI

channelwatch doctor is a real CLI surface in the current app source. Run it inside the container when you need a quick config check, a DVR connectivity sweep, a shareable debug bundle, or a DVR API-key re-encryption pass within the narrower per-DVR encryption scope documented on the security pages.

What works today

Section titled “What works today”

The older one-off CLI flags are still useful for targeted checks, and the web UI still exposes the Diagnostics panel. The doctor commands below are the current source-backed entry points for broader troubleshooting workflows.

The current release also ships four CLI flags that cover common diagnostic needs. Run them inside the container via docker exec when you need a narrower check than the broader doctor workflows:

FlagWhat it does
--test-connectivityChecks whether ChannelWatch can reach each configured DVR server
--test-apiValidates the DVR API endpoints ChannelWatch depends on
--test-alertSends a test notification through a configured provider
--monitor-eventsStreams live DVR events to the terminal for real-time inspection

See CLI Commands for usage examples and expected output for each flag.

Running doctor

Section titled “Running doctor”

Run all subcommands inside the ChannelWatch container:

Terminal window
docker exec channelwatch channelwatch doctor diagnose

The container must be running. If it will not start at all, check Common Issues first.

Subcommands

Section titled “Subcommands”

diagnose

Section titled “diagnose”
Terminal window
docker exec channelwatch channelwatch doctor diagnose

This is the main DVR sweep. For each configured, non-deleted DVR, the current implementation checks:

  • DVR connectivity - can ChannelWatch open a connection to the configured host and port?
  • DVR status - does the DVR return JSON from /status?
  • DVR version compatibility - is the reported version inside the tested range?
  • DVR authentication - does the configured DVR API key work against /api/v1/channels, or is auth required?

When a check fails, diagnose prints a remediation hint based on the current implementation.

Representative output:

Checking Living Room (192.168.1.100:8089)...
  OK version: 2025.06.15
  OK auth: Auth check passed using the configured DVR API key.


Diagnosis completed successfully for 1 DVR(s).

A failing connectivity check will look like:

Checking Living Room (localhost:8089)...
  FAIL connectivity: Hint: inside Docker, localhost points at the container. Use the DVR's LAN IP or host.docker.internal instead.

config-check

Section titled “config-check”
Terminal window
docker exec channelwatch channelwatch doctor config-check

config-check validates /config/settings.json against the real core and UI loaders without starting the full monitoring stack. It is useful after manual edits, restores, or migration recovery.

If the config is valid, it prints how many DVRs both loaders accepted. If it fails, it prints the loader error and a hint to repair or restore settings.json before rerunning the command.

debug bundle

Section titled “debug bundle”
Terminal window
docker exec channelwatch channelwatch doctor debug bundle

This command creates a sanitized zip archive. By default it writes channelwatch_debug_bundle.zip in the current working directory inside the container, or you can choose a path with --output:

Terminal window
docker exec channelwatch channelwatch doctor debug bundle --output /config/channelwatch_debug_bundle.zip

The current source-backed bundle contains:

  • manifest.json
  • settings_sanitized.json
  • logs/app.log (last 500 lines, with IPv4 addresses and URL hosts redacted)
  • health_snapshot.json

The bundle is designed for sharing in a GitHub issue or Discussions thread. Review it before sharing to confirm the sanitization meets your comfort level.

rotate-encryption-key

Section titled “rotate-encryption-key”
Terminal window
docker exec channelwatch channelwatch doctor rotate-encryption-key

The current implementation generates a new /config/encryption.key, re-encrypts stored DVR api_key values with that key, and writes a backup of the previous key to encryption.key.bak when an older key existed.

Run this if you suspect the encryption key has been compromised, or as part of a periodic security rotation.

Reading the output

Section titled “Reading the output”

diagnose uses three status labels in its output:

StatusMeaning
OKCheck passed. No action needed.
WARNSomething is unusual but not blocking. Review the hint.
FAILCheck failed. The hint explains what to fix.

A WARN on auth usually means the DVR responded with an unexpected HTTP status during the auth probe. A FAIL on version compatibility means the DVR is outside the tested range.

Common failure hints

Section titled “Common failure hints”

“Connection refused” - The DVR host or port is wrong, or the DVR server is not running. If you’re using bridge networking, the host must be the LAN IP of the machine running Channels DVR, not localhost or 127.0.0.1.

“Authentication failed” - The DVR API key stored in ChannelWatch is wrong or expired. Update it in Settings > DVR Servers.

“Config check failed” - settings.json could not be loaded by one of the real settings loaders. Repair the file or restore from /config/backups/, then rerun channelwatch doctor config-check.

“Encryption key rotation failed” - repair /config/settings.json first, then rerun the rotation command.

If you need to check the key file permissions directly, /config/encryption.key should remain readable only by the process owner:

Terminal window
chmod 600 /your/config/path/encryption.key
Section titled “Related pages”