What causes "usage: caveman-proxy usage import|link|refresh|unlink " in JuliusBrussee/caveman?

Provide the subcommand and provider: caveman-proxy usage import claude

usage: caveman-proxy usage import|link|refresh|unlink <provi

Error message

usage: caveman-proxy usage import|link|refresh|unlink <provider>

What it means

runUsage was invoked with no arguments at all, so there is no subcommand to dispatch (import/link/refresh/unlink). It fails fast with the usage string rather than defaulting to any behavior, and exits 1 via fatalJSON.

Source

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

	case "promote":
		trialID := requiredTrialID(logger, spend, args)
		optimizerID := firstPositional(args)
		if optimizerID == "" {
			fatalJSON(logger, fmt.Errorf("usage: caveman-proxy trial promote <optimizer_id> --trial-id <id>"))
		}
		plan, err := spend.BuildTrialPlan(trialID)
		if err != nil {
			fatalJSON(logger, err)
		}
		promoteMove(logger, home, trialID, optimizerID, plan)
	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 {

View on GitHub (pinned to 27d5a3981a)

Solutions

Provide the subcommand and provider: caveman-proxy usage import claude
Guard wrapper scripts: skip or fail clearly when the command variable is empty
Use the binary's help output to enumerate valid subcommands

Example fix

# before
caveman-proxy usage

# after
caveman-proxy usage import claude   # correct binary: caveman-proxy usage import claude

Defensive patterns

Strategy: validation

Validate before calling

if [ $# -eq 0 ]; then echo "usage: caveman-proxy usage import|link|refresh|unlink <provider>" >&2; exit 2; fi

Prevention

Guard wrapper scripts against empty command variables
Use --help for discovery instead of bare invocations
Treat a bare-subcommand exit 1 as a script bug, not a runtime condition

When it happens

Trigger: Bare `caveman-proxy usage` with nothing after it — typically a wrapper script that failed to interpolate its argument, or an exploratory run to 'see what it does' (use --help instead).

Common situations: Empty shell variable expansion (`caveman-proxy usage $CMD` with CMD unset); cron/systemd unit with a missing argument; users expecting a no-arg default like 'show stats'.

Related errors

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