What causes "usage: caveman-agent doctor [--json]" in JuliusBrussee/caveman?

Run `caveman-agent doctor` with no arguments, or at most `caveman-agent doctor --json`.

usage: caveman-agent doctor [--json]

Error message

usage: caveman-agent doctor [--json]

What it means

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.

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).

Example fix

// before
caveman-agent doctor ./my-project --json
// after
cd ./my-project && caveman-agent doctor --json

Defensive patterns

Strategy: validation

Validate before calling

const extra = process.argv.slice(3).filter((a) => a !== "--json");
if (process.argv[2] === "doctor" && extra.length > 0) {
  console.error("usage: caveman-agent doctor [--json]");
  process.exit(1);
}

Try / catch

try {
  await runCli(args);
} catch (e) {
  if (String(e.message).startsWith("usage: caveman-agent doctor")) {
    console.error(e.message);
    process.exit(2);
  }
  throw e;
}

Prevention

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

When it happens

Trigger: Running `caveman-agent doctor --verbose`, `doctor <project-dir>`, or any flag besides --json.

Common situations: Assuming doctor takes a project path argument (it uses process.cwd()); passing -j or --json=true shorthand.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/b272e8aabb70040a. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/cli.ts:136

type DoctorReport = {
  schema_version: 1;
  framework_version: string;
  ready: boolean;
  /** What a run on this machine would do today, with nothing else installed. */
  execution_mode: "optimized" | "observe-only";
  checks: DoctorCheck[];
  harnesses: Array<{
    id: "pi" | "claude" | "vercel-ai-sdk" | "eve" | "mastra";
    locked_execution: boolean;
    detail: string;
  }>;
  next_action: string;
};

async function doctor(args: string[]): Promise<void> {
  if (args.some((value) => value !== "--json")) {
    throw new Error("usage: caveman-agent doctor [--json]");
  }
  const json = args.includes("--json");
  const root = process.cwd();
  const checks: DoctorCheck[] = [];
  const node = process.versions.node;
  checks.push(compareNodeVersion(node, "22.19.0") >= 0
    ? { id: "node", status: "pass", detail: `Node ${node}` }
    : {
      id: "node",
      status: "fail",
      detail: `Node ${node}; framework requires >=22.19.0`,
      fix: "install Node 22.19 or newer",
    });

  try {
    if (!await verifySandboxConformance()) throw new Error("probe returned false");
    checks.push({ id: "sandbox", status: "pass", detail: "tool sandbox containment probe passed" });
  } catch (error) {

View on GitHub (pinned to 3ee70a1026)