What causes "usage: caveman-proxy trial promote --trial-id " in JuliusBrussee/caveman?

Supply the positional: caveman-proxy trial promote --trial-id

usage: caveman-proxy trial promote <optimizer_id> --trial-id

Error message

usage: caveman-proxy trial promote <optimizer_id> --trial-id <id>

What it means

The `caveman-proxy trial promote` subcommand requires an optimizer id as its first positional argument; none was found. fatalJSON logs the error as JSON and exits 1, so the process stops before BuildTrialPlan runs. The message doubles as inline usage text.

Source

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

		}
		printJSON(map[string]any{"trial_id": trialID, "report": out, "basis": plan.Basis})
	case "export":
		trialID := requiredTrialID(logger, spend, args)
		plan, err := spend.BuildTrialPlan(trialID)
		if err != nil {
			fatalJSON(logger, err)
		}
		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)

View on GitHub (pinned to 27d5a3981a)

Solutions

Supply the positional: caveman-proxy trial promote <optimizer_id> --trial-id <id>
Get valid ids first from the trial plan (export/show) so you promote one that exists
Quote shell variables and check they are non-empty: "${OPT_ID:?optimizer id required}"

Example fix

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

# after
caveman-proxy trial export --trial-id abc123   # list candidate optimizer ids
caveman-proxy trial promote compress-prefix --trial-id abc123

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$OPT_ID" ]; then echo "optimizer id required" >&2; exit 2; fi
caveman-proxy trial promote "$OPT_ID" --trial-id "$TRIAL_ID"

Prevention

Assert required positionals in wrapper scripts before invoking the CLI
Enumerate valid optimizer ids from trial export before promoting
Use shell parameter defaults with errors: ${OPT_ID:?missing optimizer id}

When it happens

Trigger: Running `caveman-proxy trial promote --trial-id <id>` with no positional optimizer_id, or putting the optimizer id after a flag in a way firstPositional does not recognize (flags consumed first, positional missing).

Common situations: Copy-pasting a shortened command from docs/notes that omits the optimizer id; assuming --trial-id alone suffices; shell quoting that swallows the argument ($OPT empty due to unset variable).

Related errors

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