{"record":{"id":"b272e8aabb70040a","repo":"JuliusBrussee/caveman","slug":"usage-caveman-agent-doctor-json","errorCode":null,"errorMessage":"usage: caveman-agent doctor [--json]","messagePattern":"usage: caveman-agent doctor \\[--json\\]","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/agent/src/cli.ts","lineNumber":136,"sourceCode":"\ntype DoctorReport = {\n  schema_version: 1;\n  framework_version: string;\n  ready: boolean;\n  /** What a run on this machine would do today, with nothing else installed. */\n  execution_mode: \"optimized\" | \"observe-only\";\n  checks: DoctorCheck[];\n  harnesses: Array<{\n    id: \"pi\" | \"claude\" | \"vercel-ai-sdk\" | \"eve\" | \"mastra\";\n    locked_execution: boolean;\n    detail: string;\n  }>;\n  next_action: string;\n};\n\nasync function doctor(args: string[]): Promise<void> {\n  if (args.some((value) => value !== \"--json\")) {\n    throw new Error(\"usage: caveman-agent doctor [--json]\");\n  }\n  const json = args.includes(\"--json\");\n  const root = process.cwd();\n  const checks: DoctorCheck[] = [];\n  const node = process.versions.node;\n  checks.push(compareNodeVersion(node, \"22.19.0\") >= 0\n    ? { id: \"node\", status: \"pass\", detail: `Node ${node}` }\n    : {\n      id: \"node\",\n      status: \"fail\",\n      detail: `Node ${node}; framework requires >=22.19.0`,\n      fix: \"install Node 22.19 or newer\",\n    });\n\n  try {\n    if (!await verifySandboxConformance()) throw new Error(\"probe returned false\");\n    checks.push({ id: \"sandbox\", status: \"pass\", detail: \"tool sandbox containment probe passed\" });\n  } catch (error) {","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/cli.ts#L118-L154","documentation":"doctor() accepts exactly zero or one argument, and that argument must be the literal --json. Any other argument (including close variants like --Json, -j, or an extra positional) throws the usage line. Doctor is a read-only diagnostic command with a deliberately tiny surface.","triggerScenarios":"Running `caveman-agent doctor --json extra`, `caveman-agent doctor -j`, `caveman-agent doctor json`, or any second/third argument where args.some(v => v !== \"--json\") becomes true.","commonSituations":"Wrappers/scripts appending passthrough arguments (e.g. `caveman-agent doctor \"$@\"` with stray args); assuming a short flag exists; CI passing a config path to doctor like build takes.","solutions":["Run bare `caveman-agent doctor` or `caveman-agent doctor --json` — nothing else is accepted.","Fix wrapper scripts so only intended flags reach doctor; filter passthrough args.","If you wanted machine output, the only supported form is the exact string --json."],"exampleFix":"# before\ncaveman-agent doctor --json --verbose\n\n# after\ncaveman-agent doctor --json","handlingStrategy":"validation","validationCode":"function validDoctorArgs(args: string[]): boolean {\n  return args.length === 0 || (args.length === 1 && args[0] === \"--json\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Doctor takes exactly zero or one argument, and that argument must be the literal --json.","Don't pass config paths or passthrough \"$@\" to doctor; filter wrapper arguments explicitly."],"tags":["cli","usage","doctor"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}