{"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":"validation","errorClass":null,"httpStatus":null,"severity":"error","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/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/cli.ts#L118-L154","documentation":"Usage error from the doctor subcommand: argv contained something other than the single accepted flag --json. The doctor command takes no positional or other arguments, so any extra token is rejected with this usage line.","triggerScenarios":"Running `caveman-agent doctor --verbose`, `doctor <project-dir>`, or any flag besides --json.","commonSituations":"Assuming doctor takes a project path argument (it uses process.cwd()); passing -j or --json=true shorthand.","solutions":["Run `caveman-agent doctor` with no arguments, or at most `caveman-agent doctor --json`.","cd into the project directory first instead of passing it as an argument.","Use the exact --json spelling (single dash pair, lowercase)."],"exampleFix":"// before\ncaveman-agent doctor ./my-project --json\n// after\ncd ./my-project && caveman-agent doctor --json","handlingStrategy":"validation","validationCode":"const extra = process.argv.slice(3).filter((a) => a !== \"--json\");\nif (process.argv[2] === \"doctor\" && extra.length > 0) {\n  console.error(\"usage: caveman-agent doctor [--json]\");\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runCli(args);\n} catch (e) {\n  if (String(e.message).startsWith(\"usage: caveman-agent doctor\")) {\n    console.error(e.message);\n    process.exit(2);\n  }\n  throw e;\n}","preventionTips":["Remember doctor reads process.cwd(); cd into the project instead of passing a path","Only the exact flag --json is accepted","Wrap doctor invocations in scripts with fixed arguments"],"tags":["cli","usage","invalid-flag"],"backgroundTag":"invalid-cli-argument","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}