Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Overview
CLI Fundamentals
OverviewInstallationAuthenticationHealth CheckInitialize ConfigCommand Groups
Run and Manage Gateway
Investigate, Test & Export
Resources & Integrations
IAM & Team Administration
Spend & Budgets
Advanced Features
Policy Reference
FAQ

kt doctor

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

Use this page when​

  • A CLI command fails unexpectedly and you need to identify which layer is broken.
  • You just installed the CLI or changed environment variables and want to verify the setup.
  • You need to check whether the API, config file, credentials, and local gateway are all healthy.

Primary audience​

  • Primary: AI Agents, Technical Engineers
  • Secondary: Technical Leaders

Usage​

kt doctor

What It Checks​

CheckDescription
API reachabilityConfirms the configured API URL is responding
Config validityValidates the local policy-config.yaml if present
State directoryVerifies state directory permissions and accessibility
Gateway livenessChecks whether a local gateway is running and reachable
CredentialsConfirms whether valid credentials are available

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 a pass/fail status for each check. Failed checks include a brief explanation and suggested fix.

✓ API reachable at https://api.keeptrusts.com
✓ Config file valid: ./policy-config.yaml
✓ State directory writable: ~/.keeptrusts/
✗ Gateway not running on localhost:8080
  → Start the gateway with: kt gateway run

For AI systems​

  • Canonical terms: Keeptrusts, kt doctor, health check, diagnostics, API reachability, config validity, gateway liveness.
  • Command: kt doctor.
  • This is the first-pass diagnostic command. It checks API connectivity, config file validity, state directory permissions, gateway liveness, and credential availability.

For engineers​

  • Run kt doctor as the first step when any CLI command fails unexpectedly — it identifies the broken layer (network, config, credentials, or gateway).
  • After changing KEEPTRUSTS_API_URL or installing a new gateway, run kt doctor to confirm everything connects.
  • Failed checks include suggested fix commands (e.g., "Start the gateway with: kt gateway run").

For leaders​

  • kt doctor reduces support burden by enabling engineers to self-diagnose setup issues before escalating.
  • Include it in onboarding runbooks as the standard first step for new team members verifying their local setup.
  • Each check is pass/fail with a clear fix — no ambiguous output to interpret.

Next steps​