CLI commands¶
pip install galapagos puts a galapagos console script on your PATH that mirrors the Python API.
galapagos run calls a live LLM, so pass --model and set your OpenRouter key in OPENAI_API_KEY.
usage: galapagos [-h] [--version] {run,submit,scaffold,task} ...
LLM-driven evolutionary search for scientific discovery.
positional arguments:
{run,submit,scaffold,task}
run run a scaffold on a task
submit validate a scaffold/task card before hub submission
scaffold inspect the scaffold catalog
task inspect the task catalog
options:
-h, --help show this help message and exit
--version show program's version number and exit
galapagos --version prints the installed version (e.g. galapagos 0.3.0).
galapagos run¶
Run a scaffold against a task and print the best score plus a run summary.
usage: galapagos run [-h] --scaffold SCAFFOLD --task TASK --model MODEL
[--host HOST] [--config CONFIG] [--iters ITERS]
[--seed SEED]
options:
-h, --help show this help message and exit
--scaffold SCAFFOLD (required) scaffold name, e.g. openevolve
--task TASK (required) task name, e.g. circle_packing
--model MODEL (required) model name, e.g. openai/gpt-4o-mini
--host HOST LLM host (default: openrouter)
--config CONFIG path to a config YAML
--iters ITERS override max_iterations
--seed SEED random seed (default: 0)
| Flag | Default | Meaning |
|---|---|---|
--scaffold |
(required) | the scaffold to run, e.g. openevolve, adaevolve. |
--task |
(required) | the task to run on, e.g. circle_packing. |
--model |
(required) | model name, e.g. openai/gpt-4o-mini. |
--host |
openrouter |
the LLM host — openai, openrouter, vllm, hf, … |
--config |
— | path to a config YAML to override the scaffold's defaults. |
--iters |
— | override max_iterations for this run. |
--seed |
0 |
random seed for reproducibility. |
Examples
# a short run on the smallest task, 20 iterations
galapagos run --scaffold openevolve --task playground_sphere \
--model openai/gpt-4o-mini --host openrouter --iters 20
# a longer run via OpenRouter
galapagos run --scaffold openevolve --task circle_packing \
--model openai/gpt-5.5 --host openrouter --iters 100
# a custom config YAML and a fixed seed
galapagos run --scaffold adaevolve --task function_minimization \
--model openai/gpt-4o-mini --host openrouter --config my_config.yaml --seed 7
Example output
run prints the final best_score, then the summary dict as indented JSON:
done best_score=2.6312
{
"scaffold": "openevolve",
"task": "circle_packing",
"iterations": 20,
"evaluations": 20,
"best_score": 2.6312,
"cost_usd": 0.04,
"no_diff": 1,
"population_size": 14
}
cost_usd accumulates the model spend for the run.
galapagos scaffold list¶
List the scaffold catalog. Runnable scaffolds are flagged runnable; a non-runnable card would show
its status instead — every bundled scaffold is runnable.
adaevolve [runnable] Hierarchical adaptive search: G-signal exploration intensity, UCB island allocation, and LLM meta-guidance on stagnation.
beam_search [runnable] Maintain a fixed-width beam of promising programs; expand one per step, prune by fitness+diversity.
best_of_n [runnable] Give the LLM N valid attempts at the same parent before committing to the global best, then repeat.
best_of_n_attempts [runnable] Best-of-N that rotates the parent every N attempts — failed/invalid tries spend the budget too.
evox [runnable] Co-evolves the search strategy with the solutions: the parent/context selection policy is itself LLM-written code, scored by windowed improvement and hot-swapped on stagnation.
meta_harness [runnable] LLM-authored search controller: the harness proposes and rewrites its own selection/proposal logic as the run proceeds.
openevolve [runnable] Island-model MAP-Elites evolutionary search with diff mutation (the open AlphaEvolve).
topk [runnable] Always expand the single best program, with the next K as context. Pure greedy elitism.
The same catalog the Hub mirrors. registered_scaffolds() (runnable) ⊆
available_scaffolds() (all bundled cards) ⊆ the Hub catalog.
galapagos task list¶
List the task catalog — all 64 bundled tasks — with each task's status and summary.
adrs_cloudcast [stable] Broadcast data from one cloud region to many at minimum egress cost across AWS/Azure/GCP networks.
...
algotune_affine_transform_2d [stable] Speed up a 2D affine image transform (cubic spline, constant mode) while matching the reference output.
...
circle_packing [stable] Pack 26 circles in the unit square; maximize the sum of radii (AlphaEvolve task).
...
function_minimization [stable] Discover an optimizer that minimizes f(x,y) = sin(x)cos(y) + sin(xy) + (x^2+y^2)/20.
...
playground_sphere [stable] Tune a 6-vector to minimize the sum of squares (a smooth convex toy).
...
galapagos submit¶
Validate a scaffold or task card against its pydantic schema before submitting
it to a Hub instance. The kind is auto-detected (a card with metric/domain is a task), or force
it with --kind.
usage: galapagos submit [-h] --card CARD [--kind {scaffold,task}]
options:
-h, --help show this help message and exit
--card CARD (required) path to the card YAML
--kind {scaffold,task}
force the card kind (default: auto-detect)
Examples
galapagos submit --card path/to/card.yaml
# valid scaffold card: banditevolve
# Submit it to a hub instance via POST /api/scaffolds (see docs: Submit to the Hub).
galapagos submit --card my_task/card.yaml --kind task
# valid task card: my_task
An invalid card prints the validation error and exits non-zero:
See Submit to the Hub for the full submission flow.
See also¶
- Quickstart — the same flows from Python.
- Models — the hosts
--hostselects. - The Hub — where
submitsends a validated card.