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

# ironrun doctor — Diagnose Configuration Problems

> ironrun doctor runs read-only checks: policy parsing, provider auth, redaction self-test, and binary resolution. Run it first when something breaks.

`ironrun doctor` is your first stop when something isn't working. It runs a complete read-only diagnostic on your ironrun setup in one shot — policy parsing, provider authentication, the redaction engine, and binary resolution for every command. It exits non-zero and points at exactly what is broken. Nothing is executed and no secrets are resolved.

## Usage

```bash theme={null}
ironrun doctor
```

## Example output

```
ironrun doctor

  ✓ ironrun.yml valid (v1, 3 command(s))
  ✓ provider 1password (ready)
  ✓ redaction self-test passed
  ✓ command "test": "go" resolves
  ✗ command "deploy": "./deploy.sh" not found on PATH

Some checks failed. See above.
```

When all checks pass:

```
ironrun doctor

  ✓ ironrun.yml valid (v2, 4 command(s))
  ✓ provider envfile (no external CLI required)
  ✓ redaction self-test passed
  ✓ command "dev": "npm" resolves
  ✓ command "test": "npm" resolves
  ✓ command "build": "npm" resolves
  ✓ command "db-migrate": "npx" resolves

All checks passed.
```

## What it checks

<Steps>
  <Step title="Policy file">
    Loads and parses `ironrun.yml` (or the path set by `--policy`). Confirms the version is supported and reports the number of commands. If this check fails, no further checks run — fix the policy and re-run.
  </Step>

  <Step title="Provider health">
    Instantiates the configured provider and runs a health check if the provider supports one. For providers with an external CLI (`1password`, `vault`, `doppler`, `infisical`), this verifies the CLI is installed on PATH and that the current credentials are valid. For providers that need no external CLI (`env`, `envfile`, `passthrough`), it reports "no external CLI required" and passes.
  </Step>

  <Step title="Redaction self-test">
    Writes a known canary value through the redaction engine and confirms that the value is replaced with `[REDACTED]` in the output. If this fails, run output could reach the agent with real secret values in it.
  </Step>

  <Step title="Command binary resolution">
    For each command in the policy, calls `exec.LookPath` on `argv[0]` to confirm the binary exists and is executable. Reports a warning (○) for commands that use a shell invocation — those will be denied at runtime. Reports a failure (✗) for binaries that can't be found.
  </Step>
</Steps>

## Exit codes

| Exit code | Meaning                   |
| --------- | ------------------------- |
| `0`       | All checks passed         |
| `1`       | One or more checks failed |

## Difference from `ironrun validate`

`ironrun validate` only parses the policy file and checks that it's syntactically valid. It does **not** check provider authentication, redaction, or binary resolution.

`ironrun doctor` runs all four checks. Use `validate` in CI to confirm a policy change is well-formed; use `doctor` when you're diagnosing a real problem on a developer machine.

<Tip>
  Run `ironrun doctor` after any of the following: initial setup, changing the provider, rotating credentials, adding a new command, or when an agent reports unexplained command failures.
</Tip>