doctor CLI

Run channelwatch doctor inside the container for a config check, a DVR connectivity sweep, a debug bundle, or account and credential recovery.

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 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:

Flag	What it does
--test-connectivity	Checks the first enabled DVR’s status and event-stream endpoints
--test-api	Checks HTTP responses from six endpoints on the first enabled DVR
--test-alert	Sends a test notification through a configured provider
--monitor-events	Streams live DVR events to the terminal for real-time inspection

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

Running doctor

Run all subcommands inside the ChannelWatch container:

docker exec channelwatch channelwatch doctor diagnose

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

Subcommands

diagnose

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.

Unlike the older diagnostic flags, this sweep includes disabled DVR entries that have not been deleted. A disabled server being offline can therefore make the command fail even while all enabled monitors are healthy.

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

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

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:

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

The current 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.

Note

The same bundle generator is also exposed through the backend download endpoint at /api/v1/debug/bundle for admin-authorized sessions. The CLI path documented here remains the most direct headless workflow. See Privacy for the zero-phone-home policy.

runtime-info

docker exec channelwatch channelwatch doctor runtime-info

Prints JSON describing the CLI process and any verified runtime-generation claim. Use it when comparing the container image with an installed app update.

The CLI process can still run from the image while the selected core and web workers use an installed generation. Its package paths do not prove which packages those other processes have loaded. Use Settings > Updates and the responding worker’s diagnostics for that comparison. See Updating ChannelWatch for the app-versus-image distinction.

reset-admin-password

docker exec -it channelwatch channelwatch doctor reset-admin-password --username admin

Replace admin with the existing administrator username. The hidden prompt asks for the new password twice. This changes the saved password; it is not a dry run. Avoid passing --password on the command line, where shell history can retain it.

Secure-login setup must already be complete and active. This command does not create a missing administrator or switch the authentication mode. See Users and permissions.

rotate-encryption-key

Caution

This command rotates the key used for per-DVR API keys and protected custom webhook URL/secret fields. It does not imply that every secret in settings.json is encrypted at rest.

docker exec channelwatch channelwatch doctor rotate-encryption-key

The current implementation generates a new /config/encryption.key and re-encrypts stored DVR api_key values and protected custom webhook URL/secret fields. Before replacement, it writes a private snapshot to /config/backups/key-recovery/encryption-key-rotation-<timestamp>-<random-token>/. The snapshot contains the pre-rotation settings.json, the previous encryption.key, and manifest.json. It does not create /config/encryption.key.bak.

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

Caution

The recovery snapshot contains both protected settings and their decrypting key. Keep the directory private and do not share it. Take a fresh full backup after rotation; older backups still need their matching key material to be fully restorable.

Reading the output

diagnose uses three status labels in its output:

Status	Meaning
OK	Check passed. No action needed.
WARN	Something is unusual but not blocking. Review the hint.
FAIL	Check 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

“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 may be wrong or expired. Follow DVR API Keys; the General server editor does not expose an API-key field in v1.6.0.

“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:

chmod 600 /your/config/path/encryption.key

Related pages

• Common Issues - fixes for the most frequent problems
• Diagnostics - web UI diagnostic tools available today
• CLI Commands - targeted CLI flags available alongside doctor
• Backup & Restore - restore config after a failed migration or edit
• Privacy - debug bundle handling and encryption scope