The doctor and other CLI commands

The binary is tavrn-node; in the container run it with docker compose exec tavrn tavrn-node <command> (node running) or docker compose run --rm tavrn tavrn-node <command> (node stopped). Every command loads and validates the configuration first and exits with code 2 on a configuration error. The global flag --dev (or TAVRN_DEV=true) selects development mode.

Command	What it does	Exit codes
serve (default)	Starts the server.	1 on an error, 3 when TAVRN_CACHE_URL is set but Valkey is unreachable at start.
check-config	Loads, validates and prints the effective configuration as JSON (no secrets: passwords in TAVRN_DATABASE_URL, TAVRN_SMTP_URL and TAVRN_CACHE_URL, secret query parameters, the Turnstile secret and the GIF key appear as ***; the OIDC client secret and the metrics token not at all), checks that the LiveKit binary is there (with voice on) and, with SSO, fetches the provider’s discovery document and keys and prints the redirect URI to register.	0 ok, 2 problem.
health [--ready]	Probes the server running in the same container or host: GET /healthz (with --ready /readyz) on the port of TAVRN_LISTEN (a wildcard address becomes loopback), 3-second timeout, nothing printed when healthy. The image’s health check.	0 healthy, 1 unhealthy or no answer.
send-test-mail <to>	Sends a test mail through TAVRN_SMTP_URL (without SMTP nothing is sent and the log says so).	0 sent, 1 failed.
doctor --peer <domain>	Runs the conformance checks against another node with this node’s configuration, keys and database and prints one line per check (pass, warn, fail, skip with a reason). The result is stored like an admin’s check (a hard failure blocks the peer). Run it while the node is running: the other node claims the probe’s keys from it.	0 ok, 1 hard failure, 2 the check could not run.
rotate-storage-key	Rotates the storage key. Stop the node first; back up the new key file afterwards. Resumable.	0 done, 1 failed.
well-known	Prints the discovery document (/.well-known/tavrn) for a static copy on the identity domain. Needs the node keys (start the node once first).	0 ok, 2 no keys.
openapi	Prints the OpenAPI specification of the node’s API as JSON.	0.

Examples:

docker compose exec tavrn tavrn-node check-config
docker compose exec tavrn tavrn-node send-test-mail you@example.org
docker compose exec tavrn tavrn-node doctor --peer community.example
docker compose exec tavrn tavrn-node well-known > well-known.json
docker compose run --rm tavrn tavrn-node rotate-storage-key      # node stopped

---

This page is generated from tavrn-node/docs/HANDBOOK.md (AGPL-3.0-only) when the website is built; its links were adapted for this site.