JuliusBrussee/caveman · error

usage: npm create @caveman-ai/agent@latest <project> [--prov

Error message

usage: npm create @caveman-ai/agent@latest <project> [--provider anthropic|openai|google] [--no-install]

What it means

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.

Source

Thrown at packages/create-caveman-agent/src/index.ts:79

  let install = true;
  const positional: string[] = [];
  for (let index = 0; index < args.length; index++) {
    const value = args[index]!;
    if (value === "--provider") {
      const candidate = args[++index];
      if (!candidate || candidate.startsWith("--")) throw new Error("--provider requires a value");
      provider = candidate;
      continue;
    }
    if (value === "--no-install") {
      install = false;
      continue;
    }
    if (value.startsWith("--")) throw new Error(`unknown option ${value}`);
    positional.push(value);
  }
  if (positional.length !== 1) {
    throw new Error(
      USAGE,
    );
  }
  return {
    target: positional[0]!,
    ...(provider === undefined ? {} : { provider }),
    install,
  };
}

async function installDependencies(directory: string): Promise<void> {
  const npmExecPath = process.env.npm_execpath;
  const windowsShell = !npmExecPath && process.platform === "win32";
  const command = npmExecPath
    ? process.execPath
    : windowsShell
      ? process.env.ComSpec ?? "cmd.exe"
      : "npm";

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Provide exactly one project name: `npm create @caveman-ai/agent@latest my-caveman-app`.
2. Quote names containing spaces so they arrive as a single positional: `"my app"`.
3. Move any npm-level flags before the `--` separator, leaving only the project name after it.

Example fix

# before
npm create @caveman-ai/agent@latest --provider anthropic
# after
npm create @caveman-ai/agent@latest my-app --provider anthropic

function exactlyOnePositional(args: string[]): boolean {
  const positional = args.filter(a => !a.startsWith("--") && !isProviderValue(args, a));
  return positional.length === 1;
}

When it happens

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

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

Related errors

• unknown command ${JSON.stringify(command)}; run caveman-agen
• 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/5fc30a1232b4514a. Report an issue: GitHub.