cli / commands / runhillclimb

hillclimb run

Start a run on a problem or a run-spec YAML.

Start a run on a problem or a run-spec YAML.

The search runs in the background and the terminal comes straight back: hillclimb watch follows it, hillclimb stop --all ends it. --no-detach keeps it in this terminal instead (Ctrl-C stops it).

hillclimb run [OPTIONS] TARGET

Arguments

argumentwhat it is
TARGET— required

Options

optionwhat it does
--budget TEXTWall-clock budget, e.g. 2h / 30m.
--agent, --backend TEXTThe coding agent that runs the operators: claude-code | codex | pi | dummy | toy (the last two need no LLM; --backend is the old spelling).
--model TEXTModel the coding agent runs, e.g. sonnet / opus.
--climber TEXTThe climber: a .py file, a climber folder, or package.module:Class (hillclimb climber list shows the catalog's). It replaces the climber: block of runs/config.yaml (or of the run spec); --set climber.params.k=v edits it. Repeat it (--climber climbers/greedy --climber climbers/gepa) for a mixed fleet: one search per climber on the problem, under one run, each tagged as an experiment.
--holdout / --no-holdoutHidden selection holdout. Default: on.
--learning / --no-learningCross-search memory (cards/claims injection + distillation); off = memory-blind experiment. Default: on.
--name TEXTRun name shown in the TUI.
--parallel-agents, --parallel-operators INTEGERConcurrent coding agents per search, one candidate each (--parallel-operators is the old spelling).
--parallel-searches INTEGER RANGEIndependent searches on the problem at once, each in the background. Default: 1.
--solution-cpus INTEGER RANGECPU cores each run of a solution may use, given to it as $HILLCLIMB_CPUS (default 1; --set concurrency.solution_cpus=N is the same).
--detach / --no-detachRun in the background (the default; hillclimb watch follows it) or in this terminal (Ctrl-C stops it). Default: on.
--parallel-replicates INTEGER RANGEHow many of a trial's replicates run at once: 0 = all (default), 1 = one after another, required when the metric measures the machine (time, throughput, memory).
--seed-from PATHIncumbent solution.py scored as the floor candidate.
--set TEXTAny config setting, dotted: --set climber.params.num_drafts=5 --set learning.enabled=false.
--experiment-set, --arm-set TEXTA setting for one experiment of a mixed fleet, EXPERIMENT:KEY=VALUE: --experiment-set gepa:concurrency.parallel_agents=1 (applied after --set; --arm-set is the old spelling).
--study TEXTTag the search as one experiment of a study (with --experiment); names a mixed fleet's study.
--experiment TEXTThe experiment name (with --study).