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.

Command Arguments

Required:

Optional:

Evaluation Requirements

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

1. Execute the modified code from your source file(s)
2. Assess its performance
3. 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 0002e071-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

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

Inspecting and Managing Runs

Inspect progress, results, and code for any run from another terminal — useful for scripting and for LLM agents driving Weco headlessly. Commands print JSON unless noted otherwise.

# Show run status and progress
weco run status <run_id>

# Show all results sorted by metric
weco run results <run_id> --top 5

# Show details for a specific step ('best' or a step number)
weco run show <run_id> --step best

# Show a code diff between steps
weco run diff <run_id> --step best --against baseline

# Update additional instructions for an active run
weco run instruct <run_id> "Focus on memory efficiency instead of speed"

# Terminate a running optimization
weco run stop <run_id>

Review Mode

Pass --require-review to weco run to approve every proposed change before it is evaluated. Each candidate solution waits in a pending-approval state until you (or your agent) inspect it, optionally rewrite it, and submit it for evaluation — only then does the optimizer propose the next step.

# Start a run that waits for your approval at each step
weco run --source model.py \
     --eval-command "python eval.py" \
     --metric accuracy \
     --goal maximize \
     --require-review

# From another terminal: list nodes awaiting approval (includes the proposed code)
weco run review <run_id>

# Optionally replace a pending node's code with your own edit
weco run revise <run_id> --node <node_id> --source model.py

# Approve: evaluate the pending node and unlock the next proposal
weco run submit <run_id> --node <node_id>

weco run status shows the same pending list without code, and weco run diff is handy for inspecting a pending change against the baseline.

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.

Sharing Runs

Create a public share link for a run — anyone with the link can view the run's optimization progress and results in the dashboard.

weco share <run_id>

# Machine-readable output (prints the bare URL only)
weco share <run_id> --output plain

The link looks like https://dashboard.weco.ai/share/<share_id>.

Setting Up Skills

Install the Weco skill into AI coding assistants so they can drive Weco for you (see the Skills guide):

# Interactive picker (defaults to all supported tools)
weco setup

# Or target a specific tool
weco setup claude-code
weco setup cursor
weco setup codex
weco setup openclaw

# Install for every supported tool at once
weco setup all

The skill is installed into the tool's skills folder in your home directory (e.g. ~/.claude/skills/weco for Claude Code). Use --local <path> to install from a local weco-skill checkout instead of downloading (for development).

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 In

Authenticate the CLI with your Weco account:

weco login

This starts a device authorization flow: Weco prints a verification link (and opens it in your browser), you approve the login on the web, and the CLI saves your credentials locally. If you run an authenticated command while logged out, Weco offers to start this flow automatically.

Setting the WECO_API_KEY environment variable takes precedence over saved credentials — useful for CI and headless agents.

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.