JuliusBrussee/caveman · error

unknown usage subcommand: %s

Error message

unknown usage subcommand: %s

What it means

The `usage` command dispatcher received a subcommand token outside its known set (import, link, refresh, unlink) and exited 1 via fatalJSON with the token echoed. Same strict-dispatch pattern as the other subcommand trees.

Source

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

			fatalJSON(logger, fmt.Errorf("unknown usage link source: %s", provider))
		}
	case "unlink":
		switch provider {
		case "claude", "anthropic":
			if err := spend.DeleteQuotaProvider("anthropic"); err != nil {
				fatalJSON(logger, err)
			}
			printJSON(map[string]any{"unlinked": "claude"})
		case "codex", "openai":
			if err := spend.DeleteQuotaProvider("openai"); err != nil {
				fatalJSON(logger, err)
			}
			printJSON(map[string]any{"unlinked": "codex"})
		default:
			fatalJSON(logger, fmt.Errorf("usage unlink needs claude|codex"))
		}
	default:
		fatalJSON(logger, fmt.Errorf("unknown usage subcommand: %s", sub))
	}
}

func runLearn(logger *slog.Logger, args []string) {
	sub := "scan"
	if len(args) > 0 {
		sub = args[0]
		args = args[1:]
	}
	home := mustHome(logger)
	spend := mustStore(logger, home)
	defer spend.Close()
	cwd, _ := os.Getwd()
	sources := strings.Split(argFlag(args, "--sources", "codex,claude,caveman"), ",")
	since := argFlag(args, "--since", "30d")

	switch sub {
	case "scan":

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Use one of: import, link, refresh, unlink
2. Run the binary with no args / --help to dump the command tree for your version
3. For usage reporting, use the stats command instead of usage

Example fix

# before
caveman-proxy usage stats

# after
caveman-proxy stats            # reporting lives here
caveman-proxy usage refresh claude  # lifecycle verbs live under usage

case "$SUB" in import|link|refresh|unlink) caveman-proxy usage "$SUB" "$@";; *) echo "unknown usage subcommand: $SUB" >&2;; esac

When it happens

Trigger: Typos (`usage impor`), or plausible-but-absent verbs: `usage stats`, `usage show`, `usage list`. Only the four link/refresh lifecycle verbs exist under usage.

Common situations: Users looking for read/report operations under usage (they live elsewhere, e.g. stats); scripts written from memory rather than help; version differences in the subcommand set.

Related errors

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

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