Skip to main content

kt doctor

The kt doctor command runs local health checks to diagnose common setup and connectivity issues.

Usage​

kt doctor

What It Checks​

CheckDescription
API reachabilityCalls the API health endpoint when an API token is available; otherwise reports a warning and skips the request
Config fileConfirms the selected config exists and contains valid YAML; use kt policy lint for schema validation
State directoryVerifies state directory permissions and accessibility
Supervisor stateReads the local gateway supervisor records and reports their lifecycle state; it does not probe a gateway HTTP listener

When To Use It​

Run kt doctor as the first diagnostic step when:

  • A managed gateway fails to start or connect
  • CLI commands return unexpected connection errors
  • After changing KEEPTRUSTS_API_URL or other environment variables
  • After a fresh installation to verify the setup

Output​

Doctor prints ok, warn, or fail state through an icon for each named check. Use --json for machine-readable output. The exact messages reflect the active profile and local state; a typical run looks like this:

  ✓ api_connectivity: API reachable at https://api.keeptrusts.com
  ✓ config_file: valid YAML at policy-config.yaml
  ✓ state_directory: state directory writable at /home/user/.keeptrusts
  ! proxy_liveness: no proxy instances registered

All checks passed.

Warnings do not make the command fail. If any check has fail status, the summary is Some checks failed. Review the output above.

kt doctor currently returns success even when a check has fail status. For automation, use kt doctor --json and inspect the per-check states instead of using the process exit code as the health signal.

Next steps​