JuliusBrussee/caveman · error
usage: caveman-proxy usage import codex|claude
Error message
usage: caveman-proxy usage import codex|claude
What it means
This is a CLI usage error from `caveman-proxy usage import`: the subcommand `import` requires exactly one positional provider argument, `codex` or `claude`. runUsage reads the provider with firstPositional(args) and calls fatalJSON when it is empty, because without it the command cannot know which local session store to import. It exits with a JSON-encoded error instead of a usage dump.
Solutions
- Add the provider positional: `caveman-proxy usage import codex` or `caveman-proxy usage import claude`.
- Pass --path and --since flags if you want to target a specific session file or time window, e.g. `caveman-proxy usage import claude --path ~/.claude/projects --since 30d`.
- Run `caveman-proxy usage` with no args to see the top-level subcommand list (import|link|refresh|unlink).
Example fix
// before caveman-proxy usage import // after caveman-proxy usage import claude --since 30d
Defensive patterns
Strategy: validation
Validate before calling
// shell if [ -z "$PROVIDER" ]; then echo "usage: caveman-proxy usage import codex|claude" >&2; exit 2; fi case "$PROVIDER" in codex|claude) ;; *) echo "provider must be codex or claude" >&2; exit 2;; esac caveman-proxy usage import "$PROVIDER"
Prevention
- Always pass the provider positional explicitly; there is no default.
- Remember import requires claude|codex exactly (no anthropic/openai aliases).
- Wrap the CLI in a shell function that validates args before exec.
When it happens
Trigger: Running `caveman-proxy usage import` with no provider positional at all (args[0] after the subcommand is empty). Note: any other non-empty value reaches the 'unknown usage source' error at main.go:620 instead.
Common situations: Typing `caveman-proxy usage import` while omitting the provider; scripting a bare `usage import` hoping defaults apply (there are none); forgetting that --path/--since are optional flags while the provider is mandatory.
Understand the failure class
Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.
Related errors
- no trial_id supplied and no trial runs exist
- unknown usage source
- usage: caveman-proxy learn applied
- usage: caveman-proxy learn apply
- usage: caveman-proxy learn simulate
AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20).
Data as JSON: /api/errors/d2673be9f2a81d0c.
Report an issue: GitHub.
Appendix: source
Thrown at proxy/cmd/caveman-proxy/main.go:602
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 3ee70a1026)