JuliusBrussee/caveman · warning · Error

unknown command ${JSON.stringify(command)}; run caveman-agen

Error message

unknown command ${JSON.stringify(command)}; run caveman-agent --help

What it means

The caveman-agent CLI dispatcher matched none of its known subcommands (dev, build, check, doctor, register) and throws with the JSON-stringified command token so odd whitespace/quoting is visible, pointing at --help. This is a usage error at the argument-parsing layer before any work starts.

Source

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

    return;
  }
  if (command === "build") {
    await build(args);
    return;
  }
  if (command === "check") {
    await check(args);
    return;
  }
  if (command === "doctor") {
    await doctor(args);
    return;
  }
  if (command === "register") {
    await register(args);
    return;
  }
  throw new Error(`unknown command ${JSON.stringify(command)}; run caveman-agent --help`);
}

function printHelp(): void {
  process.stdout.write([
    "Caveman Agent — efficiency-native TypeScript agent framework",
    "",
    "Usage:",
    "caveman-agent dev [entry] [prompt]",
    "caveman-agent build [config]",
    "caveman-agent check [config]",
    "caveman-agent doctor [--json]",
    "caveman-agent register",
    "caveman-agent --version",
    "",
  ].join("\n"));
}

type DoctorStatus = "pass" | "warn" | "fail";

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Run caveman-agent --help and re-issue with one of: dev, build, check, doctor, register.
2. Check script typos in package.json / CI config — the message shows the exact (JSON-quoted) token it received.
3. Put the subcommand first, flags after: `caveman-agent doctor --json`, not `caveman-agent --json doctor`.

Example fix

# before
npx caveman-agent bulid caveman.config.ts

# after
npx caveman-agent build caveman.config.ts

const COMMANDS = new Set(["dev", "build", "check", "doctor", "register"]);
function validateCommand(argv: string[]): string {
  const command = argv[2];
  if (!COMMANDS.has(command)) {
    console.error(`unknown command ${JSON.stringify(command)}; known: ${[...COMMANDS].join(", ")}`);
    process.exit(2);
  }
  return command;
}

function isKnownCommand(value: string): value is "dev" | "build" | "check" | "doctor" | "register" {
  return ["dev", "build", "check", "doctor", "register"].includes(value);
}

When it happens

Trigger: Running e.g. `caveman-agent bulid caveman.config.ts` (typo), `caveman-agent run`, `caveman-agent --help` as first token (help may be handled separately — if not, it lands here), or an empty/flags-first invocation where the first positional isn't a known command.

Common situations: Typos in scripts/CI YAML; using an older muscle-memory command from a previous CLI version; passing flags before the subcommand so the flag string becomes `command`.

Related errors

• usage: npm create @caveman-ai/agent@latest <project> [--prov
• usage: caveman-agent doctor [--json]
• ${key} is required
• --provider requires a value
• unknown option ${value}

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