What causes "unknown trial subcommand: %s" in JuliusBrussee/caveman?

Check spelling: valid subcommands are export and promote

unknown trial subcommand: %s

Error message

unknown trial subcommand: %s

What it means

The `trial` command dispatch received a first subcommand token that matches no known case (export, promote). fatalJSON logs 'unknown trial subcommand: <sub>' and the process exits 1 before any store work happens.

Source

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

		outDir := argFlag(args, "--out", filepath.Join(home, "exports", "trial-"+trialID))
		paths, err := spend.ExportTrial(plan, outDir)
		if err != nil {
			fatalJSON(logger, err)
		}
		printJSON(map[string]any{"trial_id": trialID, "export": paths})
	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"))
		}

View on GitHub (pinned to 27d5a3981a)

Solutions

Check spelling: valid subcommands are export and promote
Run caveman-proxy trial (no args) or --help to see the accepted set for your binary version
Pin script subcommands to the documented set of the binary version you ship

Example fix

# before
caveman-proxy trial show --trial-id abc123

# after
caveman-proxy trial export --trial-id abc123

Defensive patterns

Strategy: validation

Validate before calling

case "$1" in export|promote) exec caveman-proxy trial "$@";; *) echo "unknown trial subcommand: $1" >&2; exit 2;; esac

Prevention

Check the binary's help output for the accepted subcommand set
Pin CLI versions in scripts so the verb set cannot drift
Prefer tab-completion or named scripts over retyping subcommands

When it happens

Trigger: Running e.g. `caveman-proxy trial list`, `trial show`, or a typo like `trial expor`. The switch on sub has only "export" and "promote" arms.

Common situations: Assuming subcommands that exist in other tool families (list/show/delete); tab-completion or muscle-memory typos; scripts written against a newer/older binary with a different subcommand set.

Related errors

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