CLI Reference¶

Invocation¶

kedi SOURCE [OPTIONS] [PROGRAM_OPTIONS]
kedi -c SOURCE_TEXT [OPTIONS] [PROGRAM_OPTIONS]
kedi --idle [RUNTIME_BACKEND_OPTIONS]
kedi parse SOURCE
kedi SOURCE --parse
kedi install [PACKAGE.KEDI]
kedi add PACKAGE_NAME
kedi add git+https://github.com/OWNER/REPOSITORY.git

Use kedi --help, kedi install --help, or kedi add --help for the relevant usage surface.

-c/--command supports direct execution and --parse only. It cannot be combined with tests, evals, or optimization because those modes require a source-file identity and adjacent artifacts.

Runtime Backend Options¶

Option	Default	Meaning
`--adapter NAME`	`pydantic`	`pydantic`, `dspy`, `langchain`, `claude`, `codex`, or `acp`
`--adapter-model MODEL`	`groq:qwen/qwen3-32b`	Default model identifier

The historical option name is --adapter, but it accepts both framework adapters and harnesses. In Kedi source and the Python API, adapter and agent remain separate type-safe concepts.

Interactive Mode¶

kedi --idle starts a process-local incremental session. It uses +++ for a new fragment and ... for continuation input. Enter an empty continuation line to execute a buffered multiline fragment. :show <expression> inspects a value, help displays command help, and :exit, Ctrl+C, or Ctrl+D closes the session.

Interactive mode accepts --adapter and --adapter-model. It rejects a source file, -c/--command, program arguments, --parse, --test, --eval, and --optimize. See Interactive Execution for state persistence, native results, imports, history, and complete terminal behavior.

Validation and Generation Options¶

Option	Meaning
`--test`	Run all `@test:` cases and stop
`--eval`	Run all `@eval:` suites and stop
`--optimize`	Optimize every eligible `> optimize:` span before continuing
`--no-cache`	Disable/remove `> auto:` codegen cache for this command
`--quiet`	Suppress codegen and GEPA progress
`-p`, `--parse`	Parse source without compiling or executing

If both --test and --eval are given, tests run and return first. Avoid the ambiguous combination and invoke each validation mode separately.

Code Generation Options¶

Option	Default
`--codegen-agent`	`pydantic_ai`
`--codegen-model`	`openrouter/minimax/minimax-m2.7`
`--codegen-retries`	`5`

The alternate codegen agent is mock, intended for deterministic tests. Retries count generation stages. Generated implementations are cached beside the source as SOURCE.cache.kedi.

Optimizer Options¶

Option	Default	Meaning
`--optimizer`	`mock`	`mock` or `gepa`
`--optimizer-model`	`openrouter/minimax/minimax-m2.7`	GEPA main model
`--optimizer-reflection-model`	same	GEPA reflection model
`--optimizer-max-metric-calls`	`100`	Optimization evaluation budget
`--optimizer-model-max-tokens`	`8000`	Main-model output limit
`--optimizer-reflection-model-max-tokens`	`32000`	Reflection output limit
`--optimizer-reflection-minibatch-size`	`3`	Examples before reflection
`--optimizer-max-validation-examples`	all	Explicit validation-set cap
`--optimizer-fresh`	false	Delete prior optimized state/checkpoints

--optimize does not imply GEPA; the CLI default optimizer is mock. --optimizer-fresh removes .optimized.json, .optimized_scores.json, and .gepa/ artifacts. It does not control codegen cache.

Program Arguments¶

Unrecognized options after the source are parsed into the reserved args binding:

kedi report.kedi --incident-id 42 --dry-run

[incident_id: int] = `int(args.incident_id)`
[dry_run: bool] = `args.dry_run is True`

Hyphens normalize to underscores. --key value stores a string; a flag without a value stores True. The first duplicate option wins. Non-option extra tokens are ignored. Missing attributes read as None.

Package Commands¶

kedi install accepts zero or one manifest path and defaults to ./package.kedi. kedi add accepts exactly one registry name or credential-free GitHub git+https URL. Package subcommands reject ordinary runtime options.

Exit and Output¶

Success exits 0. Parse, compile, execution, validation, codegen, optimization, package, and usage failures exit nonzero and render source-aware diagnostics when available. Test mode exits 1 when any case fails; eval mode exits nonzero for suite/configuration failures.

Ordinary top-level return values are written to stdout. Diagnostics and failed operation details use stderr. --quiet does not hide final results or errors.