---
title: "overlane doctor"
description: "Check each agent's readiness and where the credential is kept"
---

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

# overlane doctor

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Prints one readiness state per installed agent (ready, needs_trust, degraded, not_installed, blocked) with its next repair action. With --live it also calls the service as each agent would: who-am-i, then the MCP tool list, with the stored sign-in (never printed). Cursor, Gemini CLI and Grok Build, which read a project file and keep their own sign-in, get the tool list called at the endpoint their file names, and the output says the client's own sign-in is not checked. A pass completes the agents step of onboarding (safe to repeat) and prints one prompt to try. Exits 0 only when every installed agent is ready; otherwise 5 (precondition not met), with the first repair command as the hint.

## Usage

```sh
overlane doctor [--marketplace-root DIR] [--agents claude,codex] [--live]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--marketplace-root` | string | no |  | Folder holding the built claude/ and codex/ plugin marketplaces |
| `--agents` | string | no |  | Which agents to set up or check (default: both) |
| `--live` | boolean | no |  | Also make a real round trip per agent with the stored sign-in (who-am-i and the MCP tool list), finish the agents step of onboarding and print a first prompt to try |

## Examples

```sh
overlane doctor
overlane doctor --agents claude
overlane doctor --live
```

## Behavior

- Effect: `read` (changes nothing).
- Needs credentials: no. Uses the network: yes.
- Supports `--dry-run`: no. Accepts `--force`: no.
- Machine-readable description: `overlane schema doctor`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "type": "object",
  "properties": {
    "project": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "overlane",
            "github",
            "gitlab"
          ]
        },
        "owner": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "root": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "root"
      ],
      "additionalProperties": false
    },
    "binding": {
      "type": "string",
      "enum": [
        "ok",
        "missing",
        "invalid"
      ]
    },
    "service": {
      "type": "string"
    },
    "credentials": {
      "type": "string"
    },
    "reachability": {
      "type": "string",
      "enum": [
        "reachable",
        "unreachable",
        "rejected",
        "not checked"
      ]
    },
    "agents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "agent": {
            "type": "string"
          },
          "installed": {
            "type": "boolean"
          },
          "state": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "action": {
            "type": [
              "string",
              "null"
            ]
          },
          "completionGate": {
            "type": "string"
          }
        },
        "required": [
          "agent",
          "installed",
          "state",
          "detail",
          "action",
          "completionGate"
        ],
        "additionalProperties": false
      }
    },
    "rules": {
      "type": "object",
      "properties": {
        "drifted": {
          "type": "boolean"
        },
        "revision": {
          "type": [
            "string",
            "null"
          ]
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "state": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "state"
            ],
            "additionalProperties": false
          }
        },
        "nextCommand": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "drifted",
        "revision",
        "targets",
        "nextCommand"
      ],
      "additionalProperties": false
    },
    "preset": {
      "type": "object",
      "properties": {
        "drifted": {
          "type": "boolean"
        },
        "agents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "agent": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "problems": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "agent",
              "path",
              "problems"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "drifted",
        "agents"
      ],
      "additionalProperties": false
    },
    "liveActivity": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "on",
            "off",
            "not_connected"
          ]
        },
        "waiting": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "agents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "agent": {
                "type": "string"
              },
              "reports": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "unavailable": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "agent",
              "reports",
              "unavailable"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "state",
        "waiting",
        "agents"
      ],
      "additionalProperties": false
    },
    "live": {
      "type": "object",
      "properties": {
        "ok": {
          "type": "boolean"
        },
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "agent": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "ok": {
                "type": "boolean"
              },
              "checked": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "notChecked": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "detail": {
                "type": "string"
              }
            },
            "required": [
              "agent",
              "label",
              "ok",
              "checked",
              "notChecked",
              "detail"
            ],
            "additionalProperties": false
          }
        },
        "nextStep": {
          "type": [
            "string",
            "null"
          ]
        },
        "firstPrompt": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "ok",
        "results",
        "nextStep",
        "firstPrompt"
      ],
      "additionalProperties": false
    },
    "problems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "check": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "action": {
            "type": "string"
          }
        },
        "required": [
          "check",
          "detail",
          "action"
        ],
        "additionalProperties": false
      }
    },
    "ready": {
      "type": "boolean"
    }
  },
  "required": [
    "project",
    "binding",
    "reachability",
    "agents",
    "liveActivity",
    "problems",
    "ready"
  ],
  "additionalProperties": false
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/doctor/index.mdx