> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# cordon doctor

> Diagnose common setup issues.

Runs a series of checks to diagnose common setup problems.

## Usage

```bash theme={null}
cordon doctor [--config PATH | --scope project|user]
```

| Option           | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `--config`, `-c` | Path to config file. Mutually exclusive with `--scope`.                                        |
| `--scope`        | `project` or `user`; selects which config file to inspect. Mutually exclusive with `--config`. |

## Checks performed

| Check                      | What it verifies                                                   |
| -------------------------- | ------------------------------------------------------------------ |
| Config validity            | `cordon.toml` parses and validates correctly                       |
| Cert paths                 | CA cert and key files exist at configured paths                    |
| Cert expiry                | CA certificate is not expired                                      |
| Trust store                | CA is trusted in the system trust store                            |
| Port availability          | Configured listen port is available                                |
| Service status             | Background service is running (if installed)                       |
| OS keyring session (Linux) | D-Bus session bus is available for keyring secrets                 |
| Secret providers           | Configured secret providers are detected                           |
| Service PATH (macOS)       | Background service PATH matches current session                    |
| Agent skill freshness      | Installed agent skill files match expected content and permissions |

### 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 that are healthy (config file still exists) are shown for visibility, and their running-state failures are informational only.

**Orphaned services** — installed services whose embedded `--config` path no longer exists on disk — are flagged as errors and contribute to doctor's overall error count. These accumulate when project directories are deleted or moved. Run [`cordon service cleanup`](/cli/service#cordon-service-cleanup) to review and remove them.

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

### Agent skill freshness

Doctor probes all plausible agent skill install locations (project-scope and user-scope paths for each integration). Only actually-installed skills are checked — missing files are silently skipped, so integrations you haven't set up won't appear.

For each installed skill file, doctor verifies:

* The file is a regular file (not a symlink or directory)
* Content matches the expected version embedded in the binary
* Permissions are `0444` (read-only)

A content mismatch or incorrect permissions produces a warning with a `cordon setup <integration>` remediation hint.

## Telemetry

After diagnostics finish, `cordon doctor` records a best-effort telemetry event bucketed by result: `doctor_ok`, `doctor_warning`, or `doctor_error`. This helps identify whether users are running into setup trouble without sending individual check messages, config paths, service names, routes, or credential data. Doctor sends an existing install ID when one is already present, but it does not create the install ID before the first `cordon start` install event. See [CLI telemetry and update checks](/security/overview#cli-telemetry-and-update-checks) for the full list of collection points and opt-outs.

## 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
  ✓ Agent skill (claude-code): /home/user/my-project/.claude/skills/cordon/SKILL.md — up to date

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

10 passed · 0 warnings · 0 errors
```

<Tip>
  Run `cordon doctor` as the first troubleshooting step when something isn't working.
</Tip>