JuliusBrussee/caveman · error

unknown option ${value}

Error message

unknown option ${value}

What it means

The initializer's argv loop accepts exactly three options: --provider <value>, --no-install, and one positional project name. Any other token starting with `--` is unknown and rejected with its literal text, preventing silently ignored typos from changing scaffold behavior. It fails fast before files are created.

Source

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

  provider?: string;
  install: boolean;
} {
  let provider: string | undefined;
  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

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Remove the unsupported flag — the tool supports only --provider <name> and --no-install.
2. For a typo, correct it (e.g. --noinstall → --no-install).
3. Check `npm create @caveman-ai/agent@latest -- --help` style output or the README for the current flag set of your version.

Example fix

# before
npm create @caveman-ai/agent@latest myapp --template ts
# after
npm create @caveman-ai/agent@latest myapp --provider anthropic --no-install

const KNOWN = new Set(["--provider", "--no-install"]);
function argsSupported(args: string[]): boolean {
  return args.filter(a => a.startsWith("--")).every(a => KNOWN.has(a));
}

When it happens

Trigger: Passing flags like --yes, --template, --force, or a typo such as --noinstall or --providr; anything beginning with `--` that is not --provider or --no-install.

Common situations: Users carrying habits from other create-* scaffolds (create-next-app flags), docs drift between versions of the initializer, or shell autocomplete injecting unexpected flags.

Related errors

• ${key} is required
• --provider requires a value
• unknown command ${JSON.stringify(command)}; run caveman-agen
• cave_subagent_arguments_invalid
• usage: npm create @caveman-ai/agent@latest <project> [--prov

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