CLI Flags Reference

Overview

This page provides a comprehensive reference for all command-line flags and arguments available in SkyDiscover’s CLI tools.

skydiscover-run Flags

Main command for running evolutionary discovery.

Positional Arguments

string

Position: 1st argumentDescription: Path to the initial program file to seed the search. Optional - if omitted, search starts from scratch.Example:

skydiscover-run baseline.py evaluator.py

string

required

Position: 2nd argument (or 1st if initial_program omitted)Description: Path to the evaluation file that must define an evaluate function to score generated programs.Example:

skydiscover-run evaluator.py  # No initial program

Configuration Flags

string

Alias: -cDefault: NoneDescription: Path to YAML configuration file. Defines search parameters, LLM settings, and algorithm configuration.Example:

skydiscover-run program.py eval.py --config experiments/config.yaml

See also: Configuration

string

Alias: -oDefault: Auto-generated based on search algorithm and timestampDescription: Directory path for storing results, checkpoints, programs, and logs.Example:

skydiscover-run program.py eval.py --output ./results/exp_001

Output structure:

results/exp_001/
├── checkpoints/
├── programs/
├── best_program.py
└── metadata.json

Search Parameters

integer

Alias: -iDefault: From config file, or 100 if not specifiedDescription: Maximum number of search iterations to execute. Overrides config file value.Example:

skydiscover-run program.py eval.py --iterations 1000

Note: Each iteration may generate multiple candidate programs depending on the search algorithm.

string

Alias: -sDefault: From config file, or evox if not specifiedDescription: Search algorithm to use for evolutionary discovery.Choices:

Built-in Algorithms
External Backends

evox - Default evolutionary search with configurable operators
adaevolve - Adaptive evolutionary algorithm that adjusts strategy
best_of_n - Simple best-of-N sampling without evolution
beam_search - Maintains top-K programs and expands them
topk - Top-K selection strategy

openevolve - OpenEvolve integration (requires pip install openevolve)
openevolve_native - Native OpenEvolve implementation
shinkaevolve - Shinka evolutionary search
gepa - GEPA algorithm (requires pip install gepa[full])
gepa_native - Native GEPA implementation

Example:

skydiscover-run program.py eval.py --search beam_search

LLM Configuration

string

Alias: -mDefault: From config file, or gpt-5 if not specifiedDescription: LLM model(s) for solution generation. Supports single model or comma-separated list for multi-model ensemble with automatic load balancing.Format:

Simple: model-name
With provider: provider/model-name
Multiple: model1,model2,model3

Examples:

# Single model
skydiscover-run program.py eval.py --model gpt-5

# With provider prefix
skydiscover-run program.py eval.py --model anthropic/claude-5-sonnet

# Multiple models (load balanced by weight)
skydiscover-run program.py eval.py --model "gpt-5,gemini/gemini-3-pro,anthropic/claude-5-sonnet"

Supported providers:

openai (default)
anthropic
gemini / google
Custom via --api-base

string

Default: Provider-specific default (e.g., https://api.openai.com/v1)Description: Base URL for LLM API requests. Used for local models, custom endpoints, or alternative providers.Examples:

# Local LLM server
skydiscover-run program.py eval.py --api-base http://localhost:8000/v1

# Custom OpenAI-compatible endpoint
skydiscover-run program.py eval.py --api-base https://my-proxy.com/v1

# vLLM deployment
skydiscover-run program.py eval.py \
  --api-base http://vllm-server:8000/v1 \
  --model local/llama-5-70b

Advanced Options

boolean

Default: falseDescription: Enable agentic mode for multi-file codebase editing. The LLM can read and modify multiple files in the codebase directory.Behavior:

Codebase root automatically set to dirname(initial_program)
LLM receives file system context
Mutations can span multiple files
Best for complex refactoring tasks

Example:

skydiscover-run src/algorithm.py eval.py --agentic

Output:

Agentic mode enabled (codebase: /path/to/src)

Agentic mode requires more tokens per LLM call and may be slower. Use for tasks that genuinely need multi-file context.

string

Default: NoneDescription: Path to checkpoint directory to resume from. Loads saved state including all programs, metrics, and search progress.Example:

skydiscover-run program.py eval.py \
  --checkpoint ./results/exp_1/checkpoints/checkpoint_250 \
  --iterations 500

Output:

Loading checkpoint from ./results/exp_1/checkpoints/checkpoint_250
Checkpoint loaded (iteration 250)

Notes:

The --iterations flag specifies total iterations, not additional iterations
Checkpoint must be from the same search algorithm
Evaluation function must be compatible

Logging

string

Alias: -lDefault: WARNINGDescription: Logging verbosity level for console output.Choices: DEBUG, INFO, WARNING, ERROR, CRITICALExamples:

# Debug mode - very verbose
skydiscover-run program.py eval.py --log-level DEBUG

# Info mode - progress updates
skydiscover-run program.py eval.py --log-level INFO

# Only errors
skydiscover-run program.py eval.py --log-level ERROR

Output samples:

DEBUG:skydiscover.runner:Initializing runner with config
DEBUG:skydiscover.search:Creating population with size 50
DEBUG:skydiscover.llm:Calling gpt-5 with 2341 tokens
INFO:skydiscover.search:Iteration 1/100: best_score=0.42

INFO:skydiscover.search:Iteration 1/100: best_score=0.42
INFO:skydiscover.search:Iteration 2/100: best_score=0.45 (improved!)
INFO:skydiscover.checkpoint:Saved checkpoint_50

WARNING:skydiscover.runner:No improvement in 50 iterations

skydiscover-viewer Flags

Visualization tool for completed runs.

Positional Arguments

string

required

Position: 1st argumentDescription: Path to output directory, checkpoint directory, or any directory containing program JSON files.Auto-detection order:

Direct checkpoint dir (metadata.json + programs/)
Programs subdirectory with JSON files
Latest checkpoint_N in directory
Latest in checkpoints/ subdirectory
Latest in <subdir>/checkpoints/ (e.g., island/checkpoints/)
Flat directory with *.json files

Examples:

# Output directory
skydiscover-viewer ./results/evox_20260305_143022

# Specific checkpoint
skydiscover-viewer ./results/exp_1/checkpoints/checkpoint_250

# Island run
skydiscover-viewer ./results/island_experiment

# Flat directory
skydiscover-viewer ./exported_programs

Server Options

integer

Default: 8765Description: TCP port for the web dashboard server.Example:

skydiscover-viewer ./results/exp_1 --port 9000

Access: http://localhost:9000/

string

Default: 127.0.0.1Description: Host address to bind the server. Use 0.0.0.0 for external access.Examples:

# Local only (default)
skydiscover-viewer ./results/exp_1 --host 127.0.0.1

# Allow external connections
skydiscover-viewer ./results/exp_1 --host 0.0.0.0 --port 8765

Using --host 0.0.0.0 exposes the dashboard to your network. Use SSH tunneling for secure remote access:

ssh -L 8765:localhost:8765 user@remote-server

Summary Generation

string

Default: gpt-5-mini if OPENAI_API_KEY is set, otherwise disabledDescription: LLM model for generating per-program summaries and global run analysis. Requires OPENAI_API_KEY environment variable.Examples:

# Use default model
export OPENAI_API_KEY=sk-...
skydiscover-viewer ./results/exp_1

# Use specific model
skydiscover-viewer ./results/exp_1 --summary-model gpt-5

# Disable summaries
skydiscover-viewer ./results/exp_1 --summary-model ""

Summary features:

Per-program: algorithmic changes, innovation description
Global: search trajectory, breakthrough moments, patterns
On-demand: generated when viewing program details

Environment Variables

Environment variables that affect CLI behavior:

string

Required for: OpenAI models, viewer summariesDescription: API key for OpenAI services.Example:

export OPENAI_API_KEY=sk-proj-...
skydiscover-run program.py eval.py

string

Required for: Anthropic modelsDescription: API key for Anthropic Claude models.Example:

export ANTHROPIC_API_KEY=sk-ant-...
skydiscover-run program.py eval.py --model anthropic/claude-5-sonnet

string

Required for: Google Gemini modelsDescription: API key for Google Gemini models.Example:

export GOOGLE_API_KEY=...
skydiscover-run program.py eval.py --model gemini/gemini-3-pro

Flag Combinations

Common Workflows

Quick Experiment

Minimal flags for rapid testing:

skydiscover-run seed.py eval.py --iterations 50

Production Run

Full configuration with checkpointing:

skydiscover-run program.py eval.py \
  --config production.yaml \
  --output ./results/prod_$(date +%Y%m%d) \
  --iterations 5000 \
  --log-level INFO

Multi-Model Ensemble

Load-balanced multiple LLMs:

skydiscover-run program.py eval.py \
  --model "gpt-5,anthropic/claude-5-sonnet,gemini/gemini-3-pro" \
  --search beam_search \
  --iterations 1000

Resume and Continue

Resume from checkpoint with more iterations:

skydiscover-run program.py eval.py \
  --checkpoint ./results/exp_1/checkpoints/checkpoint_500 \
  --iterations 1000

Local Model Testing

Use locally hosted LLM:

skydiscover-run program.py eval.py \
  --api-base http://localhost:8000/v1 \
  --model local/llama-5-70b \
  --iterations 100

Agentic Codebase Evolution

Multi-file editing mode:

skydiscover-run src/main.py eval.py \
  --agentic \
  --model gpt-5 \
  --iterations 200 \
  --log-level INFO

Flag Priority

When the same parameter is specified in multiple places:

CLI Flags (Highest Priority)

Command-line arguments override all other sources.

--iterations 500  # Overrides config

Configuration File

YAML config file values (when --config is provided).

max_iterations: 1000

Default Values (Lowest Priority)

Hard-coded defaults in the CLI parser.

Example:

# config.yaml
max_iterations: 1000
llm:
  models:
    - name: gpt-5

# CLI overrides iterations to 500, keeps gpt-5 from config
skydiscover-run program.py eval.py --config config.yaml --iterations 500

Exit Codes

Success

Discovery completed successfully or viewer stopped gracefully.

Error

Error occurred during execution:

File not found (program or evaluator)
Invalid configuration
Checkpoint not found
Missing required package
Evaluation failure
LLM API error

skydiscover-run

Detailed run command guide

skydiscover-viewer

Detailed viewer guide

Configuration

YAML configuration reference

Evaluators

Writing evaluation functions

Search Algorithms

Available search strategies

Quick Start

Get started tutorial

Python API

CLI Reference

Configuration

Search Algorithms

Overview

skydiscover-run Flags

Positional Arguments

Configuration Flags

Search Parameters

LLM Configuration

Advanced Options

Logging

skydiscover-viewer Flags

Positional Arguments

Server Options

Summary Generation

Environment Variables

Flag Combinations

Common Workflows

Flag Priority

Exit Codes

See Also

skydiscover-run

skydiscover-viewer

Configuration

Evaluators

Search Algorithms

Quick Start

​Overview

​skydiscover-run Flags

​Positional Arguments

​Configuration Flags

​Search Parameters

​LLM Configuration

​Advanced Options

​Logging

​skydiscover-viewer Flags

​Positional Arguments

​Server Options

​Summary Generation

​Environment Variables

​Flag Combinations

​Common Workflows

​Flag Priority

​Exit Codes

​See Also

skydiscover-run

skydiscover-viewer

Configuration

Evaluators

Search Algorithms

Quick Start

Overview

skydiscover-run Flags

Positional Arguments

Configuration Flags

Search Parameters

LLM Configuration

Advanced Options

Logging

skydiscover-viewer Flags

Positional Arguments

Server Options

Summary Generation

Environment Variables

Flag Combinations

Common Workflows

Flag Priority

Exit Codes

See Also