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
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
overlane doctor
overlane doctor --agents claude
overlane doctor --liveBehavior
- 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.
{
"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 for the status the process returns.