> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leeroo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Command-line interface for Kapso

## Overview

Kapso provides a CLI for running experiments without writing Python code.

## Basic Usage

```bash theme={null}
kapso evolve --goal "Your problem description"
```

## Options

### Goal Specification

| Option        | Short | Description                       |
| ------------- | ----- | --------------------------------- |
| `--goal`      | `-g`  | Goal/problem description (inline) |
| `--goal-file` | `-f`  | File containing goal description  |

```bash theme={null}
# Inline goal
kapso evolve --goal "Build a classifier for Iris dataset"

# From file
kapso evolve --goal-file problem.txt
```

### Basic Options

| Option         | Short | Default | Description                   |
| -------------- | ----- | ------- | ----------------------------- |
| `--iterations` | `-i`  | `10`    | Maximum experiment iterations |
| `--output`     | `-o`  | auto    | Output directory for solution |

```bash theme={null}
kapso evolve --goal "..." --iterations 10 --output ./my_solution
```

### Configuration Options

| Option           | Short | Description                                           |
| ---------------- | ----- | ----------------------------------------------------- |
| `--mode`         | `-m`  | Configuration mode (GENERIC, MINIMAL)                 |
| `--coding-agent` | `-a`  | Coding agent (aider, gemini, claude\_code, openhands) |

```bash theme={null}
kapso evolve --goal "..." --mode GENERIC --coding-agent claude_code
```

### Directory Options

| Option           | Default | Description                                                     |
| ---------------- | ------- | --------------------------------------------------------------- |
| `--eval-dir`     | `None`  | Directory with evaluation files (copied to `kapso_evaluation/`) |
| `--data-dir`     | `None`  | Directory with data files (copied to `kapso_datasets/`)         |
| `--initial-repo` | `None`  | Initial repository (local path or GitHub URL)                   |

```bash theme={null}
kapso evolve --goal "..." \
    --eval-dir ./my_evaluation/ \
    --data-dir ./my_data/ \
    --initial-repo https://github.com/owner/repo
```

### List Commands

| Option          | Description                  |
| --------------- | ---------------------------- |
| `--list-agents` | List available coding agents |

```bash theme={null}
kapso --list-agents
```

## Examples

### Simple Usage

```bash theme={null}
kapso evolve \
    --goal "Build a random forest classifier for the Iris dataset"
```

### With Evaluation and Data

```bash theme={null}
kapso evolve \
    --goal "Build a classifier with accuracy > 0.9" \
    --eval-dir ./evaluation/ \
    --data-dir ./data/
```

### Full Options

```bash theme={null}
kapso evolve \
    --goal-file problem.txt \
    --iterations 20 \
    --mode GENERIC \
    --coding-agent claude_code \
    --initial-repo https://github.com/owner/starter-repo \
    --eval-dir ./evaluation/ \
    --data-dir ./data/ \
    --output ./my_solution
```

## Output

```
============================================================
EVOLVING: Build a random forest classifier for the Iris dataset
============================================================
  Max iterations: 10
  Coding agent: from config

Running experiments...
Experiment 1: Developer agent implementing solution...
Experiment 1: Running evaluation in kapso_evaluation/...
Experiment 1: Feedback generator validating results...
Experiment 1 completed with cumulative cost: $0.125
####################################################################################################
Experiment with score 0.92:
# Solution: Random forest with GridSearchCV hyperparameter tuning...
# Feedback: Good progress! Accuracy 0.92 meets the > 0.9 target. Goal achieved.
####################################################################################################

============================================================
Evolution Complete
============================================================
Solution at: ./my_solution
Experiments run: 1
Total cost: $0.125
Stopped reason: goal_achieved
Goal achieved: True

============================================================
COMPLETED
============================================================
Solution: ./my_solution
Goal achieved: True
Final score: 0.92
Cost: $0.125
Stopped reason: goal_achieved
```

## Environment Variables

The CLI loads environment variables from `.env`:

```bash theme={null}
OPENAI_API_KEY=your-openai-api-key
GOOGLE_API_KEY=your-google-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
```

## Available Coding Agents

```bash theme={null}
$ kapso --list-agents

Available Coding Agents:
==================================================
  aider: Git-centric pair programming with diff-based editing
  gemini: Google Gemini SDK for code generation
  claude_code: Anthropic Claude Code CLI for complex refactoring
  openhands: OpenHands agent with sandboxed execution
```

## Exit Codes

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `0`  | Success                                      |
| `1`  | Error (missing arguments, failed experiment) |

## Tips

<Tip>
  **Use `kapso --list-agents`** to discover available coding agents.
</Tip>

<Warning>
  **API keys are required**. Set them in `.env` or as environment variables.
</Warning>