CLI commands¶
pip install open-galapagos puts a galapagos console script on your PATH that mirrors the Python API. galapagos run calls a live LLM, so for most scaffolds set the model through config with --set proposer.model_name=... and provide the matching provider key, for example OPENROUTER_API_KEY for OpenRouter or OPENAI_API_KEY for OpenAI. claude_code and the default meta_harness coding-agent mode instead use Claude Code subscription authentication.
usage: galapagos [-h] [--version] {run,export,submit,scaffold,task} ...
LLM-driven evolutionary search for scientific discovery.
positional arguments:
{run,export,submit,scaffold,task}
run run a scaffold on a task
export export a run directory to a trajectory interchange
format (ETIF)
submit upload a scaffold/task repo to the Galapagos Hub
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.4.0).
galapagos run¶
Run a scaffold against a task and print the best score plus a run summary.
usage: galapagos run [-h] [-v] [-q] [--log-level LOG_LEVEL] --scaffold SCAFFOLD
--task TASK [--task-source {auto,local,hub}]
[--config CONFIG]
[--set DOTTED.KEY=VALUE]
[--output-dir DIR] [--resume DIR] [--emit-etif]
options:
-h, --help show this help message and exit
-v, --verbose more logs: -v for DEBUG (model calls, accounting)
-q, --quiet fewer logs: -q for WARNING only, -qq for ERROR
--log-level LOG_LEVEL
explicit log level (DEBUG/INFO/WARNING/ERROR); overrides -v/-q
--scaffold SCAFFOLD (required) scaffold name, e.g. openevolve
--task TASK (required) task name, e.g. circle_packing
--task-source {auto,local,hub}
where to resolve --task from: auto (default: the bundled copy if shipped, else the Hub) | local (bundled/local only, never the Hub) | hub (always a fresh Hub fetch, honoring $GALAPAGOS_HUB_URL/$GALAPAGOS_HUB_TOKEN)
--config CONFIG path to a config YAML (else the scaffold's bundled preset)
--set, -S DOTTED.KEY=VALUE
override any config value by dotted path (repeatable; values are YAML-parsed).
Shorthand: pass the dotted path directly as a flag, e.g.
--proposer.model_name openai/gpt-4o-mini --general.max_iterations 200
--output-dir DIR complete run directory: write the canonical trajectory, tool ledger,
checkpoints, effective config, manifest, and best solution there
--resume DIR resume from a checkpoint dir (or a run dir -> its latest checkpoint)
--emit-etif after the run, convert the run dir to ETIF (<output-dir>/etif.json). Requires --output-dir.
The log level can also be set with the GALAPAGOS_LOG_LEVEL environment variable; an explicit
--log-level wins.
There are no bespoke --model / --iterations / --seed flags: every knob is a config value, and
--set is how you reach it. run also accepts each dotted path as a flag in its own right, so
--set proposer.model_name=openai/gpt-5.5 and --proposer.model_name openai/gpt-5.5 are the same
override. A mistyped path fails fast against the config schema rather than
silently falling back to a default.
| Flag | Default | Meaning |
|---|---|---|
--scaffold |
(required) | the scaffold to run, e.g. openevolve, adaevolve. |
--task |
(required) | the task to run on, e.g. circle_packing. |
--task-source |
auto |
where to resolve --task from: auto (the bundled copy if shipped, else the Hub), local (bundled/local only, never the Hub), or hub (always a fresh Hub fetch, honoring $GALAPAGOS_HUB_URL / $GALAPAGOS_HUB_TOKEN). See The Hub. |
--config |
— | path to a config YAML to override the scaffold's defaults. |
--set, -S |
— | override any config value with a YAML-parsed dotted path, e.g. proposer.model_name=..., general.max_iterations=20, seed=7. Any dotted path also works as a flag of its own — see below. |
--output-dir |
— | complete run directory. It automatically writes evolutionary_trajectory.jsonl, tool_calling_trajectory.jsonl, checkpoints, effective config, run.json, and the best solution. Required by meta_harness, whose archive is written to <dir>/meta_harness_D. |
--resume |
— | resume from a checkpoint directory or run directory. Not supported by meta_harness. |
--emit-etif |
— | after the run, write a trajectory (ETIF) file to <output-dir>/etif.json (needs --output-dir). |
Older scripts may still pass --trajectory-path (or its --trajectory / --traj aliases) as a
compatibility override. New commands should use only --output-dir; the canonical filename is part
of the run-directory layout.
Examples
# a short run on the smallest task, 20 iterations
galapagos run --scaffold openevolve --task function_minimization \
--set proposer.model_name=openai/gpt-4o-mini \
--set proposer.api_base=openrouter \
--set general.max_iterations=20
# a longer run via OpenRouter
galapagos run --scaffold openevolve --task circle_packing \
--set proposer.model_name=openai/gpt-5.5 \
--set proposer.api_base=openrouter \
--set general.max_iterations=100
# a custom config YAML and a fixed seed
galapagos run --scaffold adaevolve --task function_minimization \
--config my_config.yaml \
--set proposer.model_name=openai/gpt-4o-mini \
--set proposer.api_base=openrouter \
--set 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,
"best_metrics": {
"combined_score": 2.6312
},
"cost_usd": 0.04,
"no_diff": 1,
"rejected_too_long": 0,
"language": "python",
"population_size": 14
}
cost_usd accumulates the model spend for the run. The done best_score=… line goes to stderr;
the summary JSON is the only stdout output, so galapagos run … > out.json stays valid JSON.
galapagos export¶
Convert an existing run directory into a trajectory (ETIF) file — the
full record of the search as one JSON document: the candidate ledger, lineage, causal behavior
timeline, failures, population changes, model/agent/tool activity, and final evaluation. This is a
post-run step: ETIF v1.1 treats evolutionary_trajectory.jsonl as authoritative and reads the run's
metadata, checkpoint, and configuration artifacts. Older runs using evolution_events.jsonl or
trajectory.jsonl remain readable through compatibility fallbacks. You can
run it any time after a run finishes, or pass
--emit-etif to export automatically.
usage: galapagos export [-h] [-v] [-q] [--log-level LOG_LEVEL] [--format FMT]
[--out PATH.json] [--inline-threshold BYTES]
RUN_DIR
positional arguments:
RUN_DIR a run directory (from `run --output-dir DIR`)
options:
-h, --help show this help message and exit
--format, -f FMT output format: etif (default; sft/sharegpt planned)
--out, -o PATH.json output path (default: <run_dir>/etif.json)
--inline-threshold BYTES
inline candidate content up to this many bytes; larger ETIF v1.1
content is stored as a hashed artifact
(default: 8192)
| Flag | Default | Meaning |
|---|---|---|
RUN_DIR |
(required) | a run directory produced by run --output-dir DIR. |
--format, -f |
etif |
the output format. Only etif today; sft / sharegpt are planned. |
--out, -o |
<run_dir>/etif.json |
where to write the file. |
--inline-threshold |
8192 |
inline candidate content up to this size; larger ETIF v1.1 content is written as a hashed artifact. |
Examples
# export a finished run to <run_dir>/etif.json
galapagos export runs/demo
# choose the output path
galapagos export runs/demo -o out/demo.etif.json
The output path is echoed on stdout, so it composes in scripts:
See Trajectories (ETIF) for what the file contains and how to use it.
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.
ale_agent [runnable] Domain-guided tabu best-first search with 30 sibling branches and three-turn solution refinement.
algotune_agent [runnable] Command-driven algorithm optimizer with evaluation tools, profiling, multi-file edits, and best-snapshot restore.
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.
claude_code [runnable] Single-agent baseline that hands the whole search loop to one Claude Code CLI session, run inside the task's own container image by default (subscription-only billing): Claude edits the solution and runs the task's own evaluator, and the framework scores checkpoints with that same evaluator. A run scored on the host (general.eval_mode: local) gets the session as a host subprocess instead.
codex [runnable] Single-agent baseline that gives one Codex CLI session the complete search loop inside the task's own image: Codex edits and evaluates, while Galapagos independently scores every observed checkpoint.
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.
gepa [runnable] Reflective mutation over execution feedback, with Pareto-frontier candidate selection.
meta_harness [runnable] A minimal outer loop that delegates selection AND mutation to a skill-steered proposer over an append-only candidate history, returning a scalar or task-configured Pareto frontier.
openevolve [runnable] Island-model MAP-Elites evolutionary search with diff mutation (the open AlphaEvolve).
random [runnable] Uniformly sample a parent and context from the full candidate history.
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 all 1,274 bundled task cards with each card's status and summary. Five spec cards do not yet
ship a runnable seed/evaluator pair.
adrs_cloudcast [external] Broadcast data from one cloud region to many at minimum egress cost across AWS/Azure/GCP networks.
...
algotune_affine_transform_2d [stable] Speed up the AlgoTune '2D Affine Transform' reference solver while staying correct vs the reference.
...
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.
...
...
galapagos submit¶
Upload a scaffold or task repo to the Galapagos Hub — HuggingFace-Hub-style push_to_hub. The
card's directory is the repo: submit validates card.yaml against its
pydantic schema, gathers every file the card references (the components
files + assets, relative to card.yaml), and uploads the bundle so the repo appears on the
website. The kind is auto-detected (a card with metric(s)/domain is a task) or set with
--repo-type.
usage: galapagos submit [-h] [-v] [-q] [--log-level LOG_LEVEL] --card-path PATH
[--repo-type {scaffold,task}] [--repo-name ORG/NAME]
[--hub-url HUB_URL] [--token TOKEN] [--dry-run]
options:
-h, --help show this help message and exit
-v, --verbose more logs: -v for DEBUG (model calls, accounting)
-q, --quiet fewer logs: -q for WARNING only, -qq for ERROR
--log-level LOG_LEVEL explicit log level (DEBUG/INFO/WARNING/ERROR); overrides -v/-q
--card-path PATH (required) path to the card YAML — its folder is the repo
--repo-type {scaffold,task} repo kind (default: auto-detect from the card)
--repo-name ORG/NAME expected repo id; validated against the card's organization + name
--hub-url HUB_URL hub base URL (default: $GALAPAGOS_HUB_URL or https://open-galapagos.com)
--token TOKEN hub write token (default: $GALAPAGOS_HUB_TOKEN)
--dry-run validate the card + list the bundle, but do not upload
--card / --kind are accepted as aliases for --card-path / --repo-type.
Get a write token (dev issuance is open; in prod you must present a Supabase login token or the admin token):
export GALAPAGOS_HUB_TOKEN=$(curl -sX POST https://open-galapagos.com/api/auth/token \
-H 'content-type: application/json' -d '{"label":"me"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["token"])')
Examples
# preview the bundle without uploading
galapagos submit --repo-type task --card-path my_task/card.yaml --dry-run
# valid task card: my_task (our_org/my_task)
# bundle → 6 files, 0.6 KiB
# Dockerfile 61 B
# README.md 10 B
# card.yaml 554 B
# data/small/a.txt 3 B
# evaluator.py 52 B
# initial_program.py 44 B
# upload the repo (needs a token)
galapagos submit --repo-type task --card-path my_task/card.yaml
# uploaded task our_org/my_task → https://open-galapagos.com/tasks/my_task
# scaffolds are uploaded the same way (kind auto-detected)
galapagos submit --repo-type scaffold --card-path my_scaffold/card.yaml
external_resources are declared, not uploaded — the large bytes stay on their own host (HF
Datasets / S3 / GCS) and are fetched by load_task() at load time. 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 selected through model/config settings.
- The Hub — where
submitsends a validated card.