{"record":{"id":"4050e1db4ac658ce","repo":"JuliusBrussee/caveman","slug":"unknown-command-json-stringify-command-run-ca","errorCode":null,"errorMessage":"unknown command ${JSON.stringify(command)}; run caveman-agent --help","messagePattern":"unknown command (.+?); run caveman-agent --help","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/agent/src/cli.ts","lineNumber":92,"sourceCode":"    return;\n  }\n  if (command === \"build\") {\n    await build(args);\n    return;\n  }\n  if (command === \"check\") {\n    await check(args);\n    return;\n  }\n  if (command === \"doctor\") {\n    await doctor(args);\n    return;\n  }\n  if (command === \"register\") {\n    await register(args);\n    return;\n  }\n  throw new Error(`unknown command ${JSON.stringify(command)}; run caveman-agent --help`);\n}\n\nfunction printHelp(): void {\n  process.stdout.write([\n    \"Caveman Agent — efficiency-native TypeScript agent framework\",\n    \"\",\n    \"Usage:\",\n    \"caveman-agent dev [entry] [prompt]\",\n    \"caveman-agent build [config]\",\n    \"caveman-agent check [config]\",\n    \"caveman-agent doctor [--json]\",\n    \"caveman-agent register\",\n    \"caveman-agent --version\",\n    \"\",\n  ].join(\"\\n\"));\n}\n\ntype DoctorStatus = \"pass\" | \"warn\" | \"fail\";","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/cli.ts#L74-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","solutions":["Run caveman-agent --help and re-issue with one of: dev, build, check, doctor, register.","Check script typos in package.json / CI config — the message shows the exact (JSON-quoted) token it received.","Put the subcommand first, flags after: `caveman-agent doctor --json`, not `caveman-agent --json doctor`."],"exampleFix":"# before\nnpx caveman-agent bulid caveman.config.ts\n\n# after\nnpx caveman-agent build caveman.config.ts","handlingStrategy":"validation","validationCode":"const COMMANDS = new Set([\"dev\", \"build\", \"check\", \"doctor\", \"register\"]);\nfunction validateCommand(argv: string[]): string {\n  const command = argv[2];\n  if (!COMMANDS.has(command)) {\n    console.error(`unknown command ${JSON.stringify(command)}; known: ${[...COMMANDS].join(\", \")}`);\n    process.exit(2);\n  }\n  return command;\n}","typeGuard":"function isKnownCommand(value: string): value is \"dev\" | \"build\" | \"check\" | \"doctor\" | \"register\" {\n  return [\"dev\", \"build\", \"check\", \"doctor\", \"register\"].includes(value);\n}","tryCatchPattern":null,"preventionTips":["Put the subcommand immediately after the binary; flags come last.","In package.json scripts and CI YAML, spell-check subcommands — the error echoes the exact token received.","After upgrading the CLI, skim `caveman-agent --help` for renamed subcommands."],"tags":["cli","usage","arguments"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}