Skip to content

CLI Reference

Karenina provides a command-line interface for running verifications, managing presets, initializing workspaces, and starting the web server. All commands are accessed through the karenina entry point.

karenina [OPTIONS] COMMAND [ARGS]...

Global options apply to the karenina entry point itself (before any subcommand):

Option Description
--version Print the installed karenina version and exit
--help Show the command list and exit

Commands

Command Description Page
verify Run verification on a benchmark checkpoint verify
verify-status Inspect a progressive save state file and show job status verify-status
preset Manage verification presets (list, show, delete) preset
serve Start the Karenina webapp server serve
init Initialize Karenina configuration and directories init
analyze-errors Materialize a verification run (a VerificationResultSet JSON export plus the benchmark JSON-LD checkpoint) into per-failure folders for triage and Claude Code launching —
optimize Optimize prompts and instructions using GEPA optimize
optimize-history View optimization history —
optimize-compare Compare multiple optimization runs —

GEPA commands

The optimize, optimize-history, and optimize-compare commands are part of the GEPA (Guided Evolutionary Prompt Architecture) module. See optimize for details.

Quick Examples

Run verification with a preset

karenina verify checkpoint.jsonld --preset default.json

Run verification with CLI overrides

karenina verify checkpoint.jsonld --preset default.json \
  --answering-model claude-haiku-4-5 \
  --questions 0,1,2

List available presets

karenina preset list

Initialize a new workspace

karenina init

Start the web server

karenina serve --port 8080

Common Patterns

Presets vs CLI arguments

Most users start with a preset file that defines model providers, evaluation modes, and pipeline features. CLI arguments then override specific values as needed:

# Preset defines everything; CLI overrides just the model
karenina verify checkpoint.jsonld --preset claude-haiku.json --answering-model claude-sonnet-4-5

Feature flags (--abstention, --sufficiency, --embedding-check, --deep-judgment) are tri-state: --flag enables, --no-flag disables, and omitting both preserves the preset default. Embedding settings (--embedding-threshold, --embedding-model) defer to environment variables when not passed explicitly.

See Configuration Hierarchy for how presets, CLI arguments, and environment variables interact.

Progressive save and resume

For long-running verification jobs, use progressive save to periodically checkpoint progress:

# Start with progressive save (saves state every N questions)
karenina verify checkpoint.jsonld --preset default.json --progressive-save

# Check progress of a running or interrupted job
karenina verify-status results.json.state

# Resume an interrupted job (benchmark path and config are loaded from the state file)
karenina verify --resume results.json.state