This reference provides detailed information about the Weco CLI commands and their options. If ever in doubt, you can use weco --help to get a list of all the commands. Use weco <command> --help to get more information about a specific command (e.g. weco run --help).

For answers to common questions about command usage and troubleshooting, see our FAQ.

Running Optimizations

This is the primary command for starting the optimization process. It takes several arguments to configure how Weco should optimize your code.

weco directly modifies the file specified by --source during the optimization process. It is strongly recommended to use version control (like Git) to track changes and revert if needed. Alternatively, ensure you have a backup of your original file before running the command. During optimization, the source file will be temporarily modified while running the evaluation command.

Upon completion, you will be prompted with the option to update your file with the best-performing version of the code found during the run. Alternatively, you can provide the --apply-change flag to the run and resume command to update the file automatically.

Command Arguments

Required:

Argument	Description	Example
`-s, --source`	Path to the source code file that will be optimized.	`-s model.py`
`-c, --eval-command`	Command to run for evaluating the code in `--source`. This command should print the target `--metric` and its value to the terminal (stdout/stderr). See note below.	`-c "python eval.py"`
`-m, --metric`	The name of the metric you want to optimize (e.g., 'accuracy', 'speedup', 'loss'). This metric name does not need to match what's printed by your `--eval-command` exactly (e.g., its okay to use "speedup" instead of "Speedup:").	`-m speedup`
`-g, --goal`	`maximize`/`max` to maximize the `--metric` or `minimize`/`min` to minimize it.	`-g maximize`

Optional:

Argument	Description	Default	Example
`-n, --steps`	Number of optimization steps (LLM iterations) to run.	100	`-n 50`
`-M, --model`	Model identifier for the LLM to use (e.g., `o4-mini`, `claude-sonnet-4-0`). See Supported Models for the complete list of available models.	`o4-mini`	`-M o4-mini`
`-i, --additional-instructions`	Natural language description of specific instructions or path to a file containing detailed instructions to guide the LLM. Supported file formats include `.txt`, `.md`, and `.rst`.	`None`	`-i instructions.md` or `-i "Optimize the model for faster inference"`
`-l, --log-dir`	Path to the directory to log intermediate steps and final optimization result.	`.runs/`	`-l ./logs/`
`--save-logs`	Save execution output for each step to `.runs/<run-id>/outputs/step_<n>.out.txt` with a JSONL index file for tracking.	`False`	`--save-logs`
`--eval-timeout`	Timeout in seconds for each evaluation step. If the timeout is reached, the evaluation step fails and the optimization proceeds to the next step. No timeout by default.	`None`	`--eval-timeout 3600`
`--apply-change`	Automatically apply the best solution to the source file without prompting.	`False`	`--apply-change`
`--api-key`	API keys for LLM providers in the format `provider=key`. You can specify multiple providers by separating them with spaces. Only available to authenticated users.	`None`	`--api-key openai=your-openai-key gemini=your-gemini-key`

Evaluation Requirements

The command specified by --eval-command is crucial for the optimization process. It must:

Execute the modified code from --source
Assess its performance
Print the metric you specified with --metric along with its numerical value to the terminal

For example, if you set --metric speedup, your evaluation script should output a line like:

speedup: 1.5

Weco will parse this output to extract the numerical value (1.5 in this case) associated with the metric name ('speedup').

For detailed guidance on creating effective evaluation scripts, see Writing Good Evaluation Scripts.

Resuming Interrupted Runs

If your optimization run is interrupted (network issues, restart, etc.), resume from the most recent node:

# Resume an interrupted run
weco resume <run_id>

# For example
weco resume 002e071-1b67-411f-a514-36947f0c4b31

# Automatically apply the best solution without prompting
weco resume <run_id> --apply-change

# Resume with custom API keys
weco resume <run_id> --api-key openai=your-openai-key gemini=your-gemini-key

Resume Command Options

Argument	Description	Default
`run_id`	The UUID of the run to resume (required).	-
`--apply-change`	Automatically apply the best solution to the source file without prompting.	`False`
`--api-key`	API keys for LLM providers in the format `provider=key`. You can specify multiple providers by separating them with spaces. Only available to authenticated users.	`None`

Deriving Runs

A derived run branches off an existing run at a specific step. The code and metric value from that step become the baseline (step 0) of the new run — no re-evaluation, no wasted compute — and a fresh optimization loop continues from there with new LLM context.

Use this to steer the optimizer in a new direction (e.g. "now focus on memory, not speed"), add constraints partway through, explore an alternative branch from a known-good solution, or extend a completed run with more steps. The parent run is stopped by default so you don't pay for two loops at once.

All runs created by derive share a lineage with their parent — the original (non-derived) run is the lineage root, and every derive from it (or from any of its descendants) belongs to the same lineage. The dashboard shows the full tree.

# Derive from the best step seen anywhere in the lineage (default)
weco run derive <run_id>

# Derive from the best step in the specified run only
weco run derive <run_id> --from-step run-best

# Derive from a specific step number
weco run derive <run_id> --from-step 7

# Add steering instructions
weco run derive <run_id> -i "Focus on memory efficiency instead of speed"

# Override the step budget for the derived run
weco run derive <run_id> -n 50

Derive Command Options

Argument	Description	Default
`run_id`	UUID of the parent run to derive from (required).	-
`--from-step`	Where to branch from: `best` (lineage-best), `run-best` (best in this run), a step number, or a node UUID.	`best`
`-n, --steps`	Override the step count for the derived run. If omitted, the parent's step count is inherited.	`None`
`-i, --additional-instructions`	Steering instructions for the derived run (inline text or path to a `.txt`/`.md`/`.rst` file). If omitted, the parent run's instructions are inherited.	`None`
`--api-key`	API keys for LLM providers in the format `provider=key`. Separate multiple providers with spaces.	`None`
`--output`	Output mode: `rich` for the interactive UI, `plain` for machine-readable JSON output (useful for LLM agents).	`rich`

Keep the source files in your working directory consistent with the parent run before deriving. The derived loop uses your local files as the baseline if they exist — any local edits will override the inherited code from the source step. In rich mode you'll be prompted to confirm before the loop starts.

Observing External Runs

Track experiments from your own optimization loop (LLM agents, custom scripts, manual experiments) in the Weco dashboard.

# Initialize a run (prints run ID to stdout)
WECO_RUN_ID=$(weco observe init --name "my-experiment" --metric val_bpb --goal min --source train.py)

# Log experiment results
weco observe log --run-id "$WECO_RUN_ID" --step 0 --description "baseline" --metrics '{"val_bpb": 2.36}' --source train.py
weco observe log --run-id "$WECO_RUN_ID" --step 1 --description "increase batch size" --metrics '{"val_bpb": 2.26}' --source train.py
weco observe log --run-id "$WECO_RUN_ID" --step 2 --status failed --description "OOM" --metrics '{"val_bpb": 0.0}' --source train.py

All observe commands are fire-and-forget — they always exit 0 and never crash your agent's loop. For full documentation, see Weco Observe.

Credit Management

Weco provides several commands to manage your credit balance and billing.

Check Credit Balance

View your current credit balance:

weco credits balance

Purchase Additional Credits

Buy more credits with flexible amount options:

weco credits topup 25

Specify any amount greater than 2 credits (defaults to 10 if omitted).

Configure Automatic Top-up

Set up automatic credit purchases when your balance gets low:

# Enable automatic top-up
weco credits autotopup --enable

# Disable automatic top-up  
weco credits autotopup --disable

Logging Out

This command logs you out of your Weco account and removes saved authentication credentials.

weco logout

After logging out, you'll need to authenticate again the next time you run Weco.

CLI Reference