Skip to main content
Runs a series of checks to diagnose common setup problems.

​
Usage

cordon doctor

​
Checks performed

CheckWhat it verifies
Config validitycordon.toml parses and validates correctly
Cert pathsCA cert and key files exist at configured paths
Cert expiryCA certificate is not expired
Trust storeCA is trusted in the system trust store
Port availabilityConfigured listen port is available
Service statusBackground service is running (if installed)
OS keyring session (Linux)D-Bus session bus is available for keyring secrets
Secret providersConfigured secret providers are detected
Service PATH (macOS)Background service PATH matches current session

​
Installed services

Doctor partitions installed services into:
  • Project services: installed services whose config path matches the current config
  • Other installed services: services that point at some other config path
Project service failures affect the overall pass/fail result. Other installed services are shown for visibility, but their failures are informational only — they don’t cause doctor to report failure. If ./cordon.toml is missing and exactly one installed service exists, cordon doctor inspects that service automatically. If multiple installed services exist, re-run with --config for the target config.

​
Linux keyring session check

On Linux, if any routes or services use source: keyring, doctor checks whether a D-Bus session bus is available — either via DBUS_SESSION_BUS_ADDRESS or the systemd user bus socket ($XDG_RUNTIME_DIR/bus). This detects environments where the Secret Service provider is unreachable (containers, CI, SSH, headless servers) before you hit a runtime error.

​
Example output

cordon doctor

  [+] Config: /home/user/my-project/cordon.toml
  [+] CA certificate: /home/user/.config/cordon/projects/.../ca-cert.pem
  [+] CA key: /home/user/.config/cordon/projects/.../ca-key.pem
  [+] CA certificate is valid PEM and not expired
  [+] CA is in system trust store
  [+] Port 6790: available
  [+] Service 'my-project': running (PID 12345, launchd (io.codezero.cordon.my-project))
  [+] Secret providers: not configured (resolved on-demand)
  [+] Service 'my-project': PATH is current

Other installed services:
  [+] Service 'hermes': running (PID 67890, launchd (io.codezero.cordon.hermes), config: /path/to/hermes/cordon.toml)
  [+] Service 'hermes': PATH is current

All checks passed.
Run cordon doctor as the first troubleshooting step when something isn’t working.