> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/doctor.md).

# observal doctor

Diagnose local Observal state, repair managed telemetry instrumentation, remove managed instrumentation, and work with redacted support bundles.

All five workflows support `--output table|json`. JSON mode never prompts or emits human banners.

## Commands

| Command                  | Purpose                                                                  |
| ------------------------ | ------------------------------------------------------------------------ |
| `doctor`                 | Diagnose configuration, Registry metadata, skills, and harness telemetry |
| `doctor patch`           | Install or update Observal-managed telemetry instrumentation             |
| `doctor cleanup`         | Remove Observal-managed telemetry instrumentation                        |
| `doctor support bundle`  | Generate a redacted diagnostic archive                                   |
| `doctor support inspect` | Inspect a diagnostic archive without extracting it                       |

## Diagnose

```bash
observal doctor --output json
```

Doctor checks:

* Local authentication configuration and server health
* Registry lockfile metadata against the active Registry
* Managed hooks, plugins, or extensions for all registered harnesses
* UUID-attributed Kiro Agent hooks
* Bundled Observal skill installation

JSON diagnosis exits zero when the checks ran successfully. Health is reported through `healthy`, `issues`, and `warnings`:

```json
{
  "healthy": false,
  "issues": ["Cannot reach the configured server"],
  "warnings": ["Cursor session push hooks are not installed"],
  "lockfile_changes": [],
  "skill_missing": [],
  "fix_attempted": false,
  "patch": null
}
```

Human mode retains health-check behavior: unresolved issues exit nonzero. Warnings alone remain successful.

Apply fixable warnings and canonical lockfile metadata without prompting:

```bash
observal doctor --yes --output json
```

Installed version pins are not changed. Only Observal-managed telemetry entries are updated.

## Patch

Preview every registered harness:

```bash
observal doctor patch --all-harnesses --dry-run --output json
```

Patch selected harnesses:

```bash
observal doctor patch --harness claude-code --harness kiro --output json
```

Exactly one target mode is required: `--all-harnesses` or one or more `--harness` options. JSON returns one result per harness:

```json
{
  "action": "patch",
  "dry_run": false,
  "changed": true,
  "targets": [
    {"harness": "kiro", "changed": true}
  ]
}
```

Patch is idempotent. It preserves unrelated hooks and configuration. Configuration writes are atomic. Invalid or unreadable harness files fail loudly rather than being replaced.

For Pi, patch installs the bundled TypeScript extension at `~/.pi/agent/extensions/observal.ts` and removes the legacy npm package registration. MCP commands and remote URLs are never wrapped or rewritten.

## Cleanup

Preview cleanup:

```bash
observal doctor cleanup --dry-run --output json
```

Remove instrumentation from one harness:

```bash
observal doctor cleanup --harness goose --yes --output json
```

Remove instrumentation from all registered harnesses except selected entries:

```bash
observal doctor cleanup --exclude kiro --yes --output json
```

Cleanup removes only Observal-managed hooks, plugins, extensions, and legacy telemetry settings. User-owned hooks remain. Human mode confirms before writing unless `--yes` is present. JSON cleanup requires `--yes` unless it is a dry run.

Unknown harnesses, conflicting selections, malformed configuration, and write failures are surfaced before success is reported.

## Support bundles

```bash
observal doctor support bundle --output json
observal doctor support inspect ./observal-support.tar.gz --output json
```

See [Support bundles](/cli-reference/doctor/support.md) for archive contents, redaction, offline behavior, and inspection limits.

## Exit codes

| Code | Meaning                                                                                    |
| ---- | ------------------------------------------------------------------------------------------ |
| 3    | Authentication is required for patching                                                    |
| 5    | Support bundle or requested bundle file not found                                          |
| 6    | Output archive already exists                                                              |
| 7    | Invalid harness selection, malformed harness file, invalid bundle, or missing confirmation |
| 9    | Server, collector, or filesystem unavailable                                               |

## Related

* [`observal scan`](/cli-reference/scan.md): read-only harness inventory
* [`observal agent pull`](/cli-reference/pull.md): install a complete Agent
* [Session tracking](/core-concepts/session-tracking.md): telemetry delivery architecture


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/doctor.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.