{"record":{"id":"5fc30a1232b4514a","repo":"JuliusBrussee/caveman","slug":"usage-npm-create-caveman-ai-agent-latest-projec","errorCode":null,"errorMessage":"usage: npm create @caveman-ai/agent@latest <project> [--provider anthropic|openai|google] [--no-install]","messagePattern":"usage: npm create @caveman-ai/agent@latest <project> \\[--provider anthropic\\|openai\\|google\\] \\[--no-install\\]","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/create-caveman-agent/src/index.ts","lineNumber":79,"sourceCode":"  let install = true;\n  const positional: string[] = [];\n  for (let index = 0; index < args.length; index++) {\n    const value = args[index]!;\n    if (value === \"--provider\") {\n      const candidate = args[++index];\n      if (!candidate || candidate.startsWith(\"--\")) throw new Error(\"--provider requires a value\");\n      provider = candidate;\n      continue;\n    }\n    if (value === \"--no-install\") {\n      install = false;\n      continue;\n    }\n    if (value.startsWith(\"--\")) throw new Error(`unknown option ${value}`);\n    positional.push(value);\n  }\n  if (positional.length !== 1) {\n    throw new Error(\n      USAGE,\n    );\n  }\n  return {\n    target: positional[0]!,\n    ...(provider === undefined ? {} : { provider }),\n    install,\n  };\n}\n\nasync function installDependencies(directory: string): Promise<void> {\n  const npmExecPath = process.env.npm_execpath;\n  const windowsShell = !npmExecPath && process.platform === \"win32\";\n  const command = npmExecPath\n    ? process.execPath\n    : windowsShell\n      ? process.env.ComSpec ?? \"cmd.exe\"\n      : \"npm\";","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/create-caveman-agent/src/index.ts#L61-L97","documentation":"The USAGE error is thrown when the positional (non-flag) argument count is not exactly one: the initializer requires precisely one project target. Zero positionals (only flags given) and multiple positionals both trigger it. The message doubles as the full usage string so the correction is visible immediately.","triggerScenarios":"`npm create @caveman-ai/agent@latest` with no project name, or with two+ names such as `myapp extra`, since only flags are stripped from argv before the positional count check.","commonSituations":"Forgetting the project name entirely, passing a quoted multi-word name that the shell splits, or adding trailing arguments intended for npm rather than the initializer.","solutions":["Provide exactly one project name: `npm create @caveman-ai/agent@latest my-caveman-app`.","Quote names containing spaces so they arrive as a single positional: `\"my app\"`.","Move any npm-level flags before the `--` separator, leaving only the project name after it."],"exampleFix":"# before\nnpm create @caveman-ai/agent@latest --provider anthropic\n# after\nnpm create @caveman-ai/agent@latest my-app --provider anthropic","handlingStrategy":"validation","validationCode":"function exactlyOnePositional(args: string[]): boolean {\n  const positional = args.filter(a => !a.startsWith(\"--\") && !isProviderValue(args, a));\n  return positional.length === 1;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the project name as the first non-flag argument.","Quote names containing spaces.","Put npm-level flags before `--` and initializer args after it."],"tags":["cli","usage","arguments"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}