JuliusBrussee/caveman · error

usage: caveman-proxy usage import codex|claude

Error message

usage: caveman-proxy usage import codex|claude

What it means

The `usage import` subcommand requires a provider positional (codex or claude) and none was supplied. fatalJSON prints this usage line and exits 1 before any import runs.

Source

Thrown at proxy/cmd/caveman-proxy/main.go:480

	default:
		fatalJSON(logger, fmt.Errorf("unknown trial subcommand: %s", sub))
	}
}

func runUsage(logger *slog.Logger, args []string) {
	if len(args) == 0 {
		fatalJSON(logger, fmt.Errorf("usage: caveman-proxy usage import|link|refresh|unlink <provider>"))
	}
	sub := args[0]
	args = args[1:]
	home := mustHome(logger)
	spend := mustStore(logger, home)
	defer spend.Close()
	provider := firstPositional(args)
	switch sub {
	case "import":
		if provider == "" {
			fatalJSON(logger, fmt.Errorf("usage: caveman-proxy usage import codex|claude"))
		}
		path := argFlag(args, "--path", "")
		since := argFlag(args, "--since", "")
		switch provider {
		case "codex":
			out, err := spend.ImportCodex(path, since)
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		case "claude":
			out, err := spend.ImportClaude(path, since)
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		default:
			fatalJSON(logger, fmt.Errorf("unknown usage source: %s", provider))

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Add the provider positional: caveman-proxy usage import claude --path ... --since ...
2. Verify provider spelling — exactly codex or claude
3. In scripts, assert the variable is set before invoking

Example fix

# before
caveman-proxy usage import --path ~/codex.jsonl

# after
caveman-proxy usage import codex --path ~/codex.jsonl

if [ -z "$PROVIDER" ]; then echo "provider required: codex|claude" >&2; exit 2; fi
caveman-proxy usage import "$PROVIDER"

When it happens

Trigger: Running `caveman-proxy usage import --path ~/logs` without the provider token; flags present but positional missing, since firstPositional only sees non-flag args.

Common situations: Reordered arguments copied from a different tool's syntax; provider supplied as --provider claude (a flag) instead of a positional; empty PROVIDER variable in scripts.

Related errors

• usage: caveman-proxy trial promote <optimizer_id> --trial-id
• unknown trial subcommand: %s
• usage: caveman-proxy usage import|link|refresh|unlink <provi
• unknown usage source: %s
• unknown usage link source: %s

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