JuliusBrussee/caveman · warning · Error

usage: caveman-agent doctor [--json]

Error message

usage: caveman-agent doctor [--json]

What it means

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.

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 27d5a3981a)

Solutions

1. Run bare `caveman-agent doctor` or `caveman-agent doctor --json` — nothing else is accepted.
2. Fix wrapper scripts so only intended flags reach doctor; filter passthrough args.
3. If you wanted machine output, the only supported form is the exact string --json.

Example fix

# before
caveman-agent doctor --json --verbose

# after
caveman-agent doctor --json

function validDoctorArgs(args: string[]): boolean {
  return args.length === 0 || (args.length === 1 && args[0] === "--json");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unknown command ${JSON.stringify(command)}; run caveman-agen
• usage: npm create @caveman-ai/agent@latest <project> [--prov
• usage: sign-binary-checksums.mjs <checksums.txt> <output.key
• cave_harness_request_invalid
• cave_eve_terminal_${result.status}

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/b272e8aabb70040a. Report an issue: GitHub.