Kapso CLI reference: every command, flag and default

Kapso installs a single kapso executable with nine commands.

Command	What it does
`kapso evolve`	Build software from a goal through experimentation
`kapso research`	Deep web research for an objective
`kapso learn`	Trajectory learning: import, mine, grade, update, codify
`kapso deploy`	Deploy a solution as running software
`kapso index_kg`	Index a knowledge graph from a wiki or JSON
`kapso watch`	Watch a running operation
`kapso inbox`	What a paused campaign is waiting on you for, and the reply that resumes it
`kapso bank`	Manage the lesson bank’s share remote
`kapso doctor`	Check this machine can run what your config asks for

Global options

Flag	What it does
`-h`, `--help`	Show help for the command and exit
`--list-agents`	List the available coding agents with their models and install commands

kapso --list-agents

On a standard install the five agents are claude_code, codex, gemini, openhands and oss_claude_code; the legacy aider extra registers a sixth.

kapso evolve

Runs an experiment campaign against a goal and returns the best solution.

Flag	What it does	Default
`-g`, `--goal`	Goal or problem description. A resume takes it from the checkpoint	—
`-f`, `--goal-file`	File containing the goal. Mutually exclusive with `--goal`	—
`-i`, `--iterations`	Maximum experiments to run. A resume keeps the launch’s cap	`10`
`-o`, `--output`	Output directory	—
`--time-budget-minutes`	Wall-clock budget for the campaign, durable across resumes	—
`--cost-budget`	Best-effort spend budget in USD	—
`--finalization-reserve-minutes`	Wall-clock escrowed for final checkout and evaluation	—
`--resume`	Continue the compatible checkpoint in `--output`. The goal and every launch flag come from the checkpoint and launch record; pass only what changes, such as a bigger budget	off
`-m`, `--mode`	Config mode: `GENERIC` or `MINIMAL`	from config (`default_mode`)
`-a`, `--coding-agent`	One of `claude_code`, `codex`, `gemini`, `openhands`, `oss_claude_code`	from config
`--eval-dir`	Evaluation files directory	—
`--data-dir`	Data files directory	—
`--initial-repo`	Starting repository, as a path or GitHub URL	—
`--kg-index`	Path to a `.index` file for knowledge search	—

kapso evolve --goal "Build a web scraper for news articles"
kapso evolve --goal-file problem.txt --iterations 20
kapso evolve --goal "Build a classifier" --eval-dir ./eval/ --data-dir ./data/
kapso evolve --output ./campaign --resume

When a session needs something only you can provide, the campaign pauses: the summary block says WAITING ON YOU instead of COMPLETED, the exit code stays 0, and kapso inbox reply resumes it. See the inbox.

kapso research

Runs deep web research and writes structured findings.

Flag	What it does	Default
`--objective`	Research objective	—
`--objective-file`	File containing the objective. Mutually exclusive with `--objective`	—
`--mode`	`idea`, `implementation` or `study`. Repeat the flag for more than one	`idea` and `implementation`
`--depth`	`light` or `deep`	`deep`
`-o`, `--output`	Output file for results, as JSON	—

kapso research --objective "How to optimize transformers?"
kapso research --objective "LLM fine-tuning" --mode idea
kapso research --objective "RAG implementation" --mode idea --mode implementation
kapso research --objective-file topic.txt --mode study --depth deep

kapso learn

Trajectory learning. Ten subcommands cover importing finished campaigns, mining them, grading a bank, and folding results back in.

Subcommand	What it does
`import`	Import archived campaign tarballs into the trajectory store
`mine`	Mine store-resident trajectories into their derived `mined/` views
`grade`	Grade a bank against held-out trajectories, or one arriving trajectory
`update`	Run the update crew: fold mined and graded trajectories into the bank
`init-bank`	Create the bank home: a bare repo plus the founding skeleton
`develop`	Run one learner version through the development regime
`codify`	Run one codify request, which is evolve minus ideation, against the bank
`ingest`	Operating-regime chain for one campaign: mine, exam, lesson
`gauntlet`	Run the duplicate and stability traps against a completed development run
`behave`	Run behavior scenarios as semantic production tests

Every subcommand takes --config to point at a config other than the packaged config.yaml.

kapso learn import

Flag	What it does	Required
`--subset`	Subset YAML of `trajectories: [{id, archive, role}]`	no
`--archive`	One archive URI or path ending `.tgz`	no
`--id`	Trajectory id override, used with `--archive`	no
`--no-upload`	Skip remote upload even when one is configured	no

kapso learn import --subset docs/plans/learning/d1-subset.yaml
kapso learn import --archive gs://bucket/runs/campaign/20260731T092629_lane-a2.tgz

kapso learn mine

Flag	What it does	Required
`--trajectory`	One trajectory id	no
`--all`	Mine every un-mined imported trajectory	no
`--force`	Regenerate even when already mined	no

kapso learn mine --all

kapso learn grade

Flag	What it does	Required
`--bank`	Bank checkout directory	yes
`--bank-head`	The graded bank head, as an `lr_` tag or a sha	yes
`--split`	Split manifest, for full mode	no
`--learner-version`	Learner version under exam, for full mode	no
`--trajectory`	One trajectory id, for exam mode	no

kapso learn grade --bank ./bank --bank-head lr_042 --split splits/d1.yaml

kapso learn update

Flag	What it does	Required
`--learner-version`	Crew version identifier	yes
`--batch-manifest`	YAML list of `{trajectory, hindcast_report}`. Omit for docket-only consolidation	no
`--split`	Split manifest. On development runs this asserts batch and held-out are disjoint	no

kapso learn update --learner-version v3 --batch-manifest batch.yaml

kapso learn init-bank

Creates the bank home. Takes only --config.

kapso learn init-bank

kapso learn develop

Flag	What it does	Required
`--split`	Split manifest	yes
`--learner-version`	Crew version identifier	yes

kapso learn develop --split splits/d1.yaml --learner-version v3

kapso learn codify

Flag	What it does	Required
`--request`	Request YAML naming the card, fixture, materials and gates	yes

kapso learn codify --request requests/card-117.yaml

kapso learn ingest

Flag	What it does	Required
`--trajectory`	Trajectory id in the store	yes
`--learner-version`	Crew version doing the lesson	yes

kapso learn ingest --trajectory rel-hm-user-churn-a2 --learner-version v3

kapso learn gauntlet

Flag	What it does	Required
`--learner-version`	Completed development run to trap	yes

kapso learn gauntlet --learner-version v3

kapso learn behave

Flag	What it does	Required
`--scenario`	One scenario directory	no
`--all`	Run every scenario	no

kapso learn behave --all

kapso deploy

Turns a solution directory into running software.

Flag	What it does	Default
`--solution-path`	Path to the solution code. Required	—
`--strategy`	`auto`, `local`, `docker`, `modal`, `bentoml` or `langgraph`	`auto`
`--goal`	Goal description for the solution	—
`--env`	Environment variable as `KEY=VALUE`. Repeat for more than one	—
`--coding-agent`	Agent behind the selector and adapter sessions	from config (`deployment.coding_agent`)
`--model`	Model that agent is asked for	from config (`deployment.model`)
`--interactive`	Keep running after deploy instead of returning	off

kapso deploy --solution-path ./solution
kapso deploy --solution-path ./solution --strategy docker
kapso deploy --solution-path ./solution --env API_KEY=xxx --interactive

kapso index_kg

Indexes a corpus into the knowledge graph and writes a .index file that campaigns load with --kg-index.

Flag	What it does	Default
`--save-to`	Path to write the `.index` file. Required	—
`--wiki-dir`	Wiki directory to index. Mutually exclusive with `--data-path`	—
`--data-path`	JSON data file to index	—
`--search-type`	`kg_graph_search` or `kg_llm_navigation`	from config
`--force`	Clear existing data before indexing	off

kapso index_kg --wiki-dir ./data/wikis --save-to ./data/indexes/ml.index
kapso index_kg --data-path ./data/kg_data.json --save-to ./data/indexes/kaggle.index
kapso index_kg --wiki-dir ./data/wikis --save-to ./data/indexes/ml.index --force

Indexing needs Weaviate and Neo4j running. See Optional: knowledge-graph backends.

kapso watch

Renders the status of a running evolve, learn or learn_knowledge operation.

Argument	What it does	Default
`path`	Workspace, status file, or directory of status files. Required	—
`--json`	Print the status file once, as JSON	off
`--follow`	Re-render on each heartbeat until the operation ends	off

kapso watch ./campaign
kapso watch learning/status
kapso watch ./campaign --follow
kapso watch ./campaign --json | jq -r '[.state] | @tsv'

kapso inbox

What a paused campaign is waiting on you for, and the reply that resumes it. Inside a campaign directory both forms act on that campaign; elsewhere, name it first. See the inbox.

Form	What it does
`kapso inbox [CAMPAIGN]`	The open requests of the campaign named, else of the one the current directory is inside, else of every registered campaign that is waiting
`kapso inbox reply [CAMPAIGN] [ID] [NOTE]`	Record the reply and resume the campaign in the foreground. The id may be left out when one request is open; an empty note means done

Flag	What it does	Default
`--yes`	Store a reply shaped like a credential anyway. Put it at the end of the line	off
`--config`	Config whose `inbox.registry` lists the campaigns	packaged `config.yaml`

kapso inbox
kapso inbox ./campaign
kapso inbox reply 1 "added the key"
kapso inbox reply ./campaign 1

kapso bank

The lesson bank is local-only by default. These two subcommands give it a git remote. Credentials stay with git and gh; Kapso never handles them.

kapso bank connect

Argument	What it does	Required
`url`	Git URL of the bank repository, https or ssh	yes

kapso bank connect https://github.com/your-org/kapso-bank.git

kapso bank create

Creates the GitHub repository with the gh CLI, then connects it.

Argument	What it does	Default
`slug`	`org/name` for the new repository. Required	—
`--public`	Create the repository public	private

kapso bank create your-org/kapso-bank

kapso doctor

Reports the requirements your active config implies, and exits non-zero when a required item is missing.

Argument	What it does	Default
`verb`	Narrow the report to `research`, `learn_knowledge`, `evolve`, `learn` or `deploy`	union of all five
`--models`	Live-probe each configured CLI and model pair, spending a few one-token calls	off
`--config`	Config to check	packaged `config.yaml`

kapso doctor
kapso doctor evolve
kapso doctor evolve --models

See How do I check my setup? for the output format and what each marker means.

Python API

The same operations from Python

Configuration

Every key in config.yaml

Related pages: Python API · Configuration · Python API Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

​Global options

​kapso evolve

​kapso research

​kapso learn

​kapso learn import

​kapso learn mine

​kapso learn grade

​kapso learn update

​kapso learn init-bank

​kapso learn develop

​kapso learn codify

​kapso learn ingest

​kapso learn gauntlet

​kapso learn behave

​kapso deploy

​kapso index_kg

​kapso watch

​kapso inbox

​kapso bank

​kapso bank connect

​kapso bank create

​kapso doctor

​Related

Python API

Configuration

Global options

kapso evolve

kapso research

kapso learn

kapso learn import

kapso learn mine

kapso learn grade

kapso learn update

kapso learn init-bank

kapso learn develop

kapso learn codify

kapso learn ingest

kapso learn gauntlet

kapso learn behave

kapso deploy

kapso index_kg

kapso watch

kapso inbox

kapso bank

kapso bank connect

kapso bank create

kapso doctor

Related