CLI Reference

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`

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

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

On this page