Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/skydiscover-ai/skydiscover/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
initial_program
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
​
evaluation_file
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

​
--config
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
​
--output
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

​
--iterations
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.
​
--search
string
Alias: -sDefault: From config file, or evox if not specifiedDescription: Search algorithm to use for evolutionary discovery.Choices:
  • 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
Example:
skydiscover-run program.py eval.py --search beam_search

​
LLM Configuration

​
--model
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
​
--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

​
--agentic
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.
​
--checkpoint
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

​
--log-level
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

​
skydiscover-viewer Flags

Visualization tool for completed runs.

​
Positional Arguments

​
path
string
required
Position: 1st argumentDescription: Path to output directory, checkpoint directory, or any directory containing program JSON files.Auto-detection order:
  1. Direct checkpoint dir (metadata.json + programs/)
  2. Programs subdirectory with JSON files
  3. Latest checkpoint_N in directory
  4. Latest in checkpoints/ subdirectory
  5. Latest in <subdir>/checkpoints/ (e.g., island/checkpoints/)
  6. 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

​
--port
integer
Default: 8765Description: TCP port for the web dashboard server.Example:
skydiscover-viewer ./results/exp_1 --port 9000
Access: http://localhost:9000/
​
--host
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

​
--summary-model
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:
​
OPENAI_API_KEY
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
​
ANTHROPIC_API_KEY
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
​
GOOGLE_API_KEY
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

Minimal flags for rapid testing:
skydiscover-run seed.py eval.py --iterations 50
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
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 from checkpoint with more iterations:
skydiscover-run program.py eval.py \
  --checkpoint ./results/exp_1/checkpoints/checkpoint_500 \
  --iterations 1000
Use locally hosted LLM:
skydiscover-run program.py eval.py \
  --api-base http://localhost:8000/v1 \
  --model local/llama-5-70b \
  --iterations 100
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:
1

CLI Flags (Highest Priority)

Command-line arguments override all other sources.
--iterations 500  # Overrides config
2

Configuration File

YAML config file values (when --config is provided).
max_iterations: 1000
3

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

​
0
Success
Discovery completed successfully or viewer stopped gracefully.
​
1
Error
Error occurred during execution:
  • File not found (program or evaluator)
  • Invalid configuration
  • Checkpoint not found
  • Missing required package
  • Evaluation failure
  • LLM API error

​
See Also

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

Build docs developers (and LLMs) love

Get started for freeTalk to us