Skip to content

karenina init

Initialize a Karenina workspace with configuration files and directories.

karenina init [OPTIONS]

The init command creates the files and directories needed for a Karenina workspace. It offers two setup modes: a quick setup with sensible defaults, and an advanced guided setup that lets you customize every setting.

If configuration already exists (defaults.json present), init asks for confirmation before overwriting. Use --force to skip this prompt.

Options

Option Short Type Default Description
--dir -d PATH current directory Working directory for Karenina data
--advanced -a flag False Run advanced setup with all options
--force -f flag False Overwrite existing configuration

Quick Setup (Default)

Running karenina init with no flags performs a quick setup using sensible defaults:

karenina init

This creates the following workspace structure:

your-project/
├── defaults.json       # Default LLM provider and model settings
├── .env                # Environment variables (paths, async, API keys)
├── dbs/                # SQLAlchemy database files
├── presets/            # Verification preset files
├── mcp_presets/        # MCP-specific preset files
└── checkpoints/        # Checkpoint (.jsonld) files

Quick setup defaults:

Setting Default Value
Provider anthropic
Model claude-haiku-4-5
Interface langchain
Async enabled true
Async workers 2

Created Files

defaults.json

Stores default LLM configuration used by the GUI and server:

{
  "default_interface": "langchain",
  "default_provider": "anthropic",
  "default_model": "claude-haiku-4-5",
  "default_endpoint_base_url": ""
}

.env

Stores environment variables for directory paths, async settings, and API key placeholders:

# Karenina Configuration (generated by karenina init)
DB_PATH=./dbs
KARENINA_PRESETS_DIR=./presets
MCP_PRESETS_DIR=./mcp_presets
KARENINA_ASYNC_ENABLED=true
KARENINA_ASYNC_MAX_WORKERS=2

# API Keys
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# GOOGLE_API_KEY=

The .env file is created with restricted permissions (chmod 600) to protect API keys.

Created Directories

Directory Purpose Related Env Var
dbs/ SQLAlchemy database files for storing verification results DB_PATH
presets/ Verification preset JSON files KARENINA_PRESETS_DIR
mcp_presets/ MCP-specific preset files MCP_PRESETS_DIR
checkpoints/ Checkpoint (.jsonld) benchmark files —

If a directory already exists, karenina init skips it without error.

Advanced Setup

Use --advanced (or -a) for a guided setup that prompts for every setting:

karenina init --advanced

The advanced setup prompts for:

  1. Directory configuration — Custom paths for databases, presets, MCP presets, and checkpoints
  2. Default LLM configuration — Provider (openai, anthropic, google_genai, openrouter) and model name
  3. Performance configuration — Enable/disable async processing and set worker count
  4. API keys — Optionally enter API keys during setup (stored in .env)

Provider-specific default models:

Provider Default Model
anthropic claude-haiku-4-5
openai gpt-4.1-mini
google_genai gemini-pro
openrouter anthropic/claude-haiku-4-5

Overwriting Existing Configuration

If defaults.json already exists, karenina init prompts for confirmation. Use --force to skip this:

karenina init --force           # Reset with quick defaults
karenina init --advanced --force  # Reset with guided setup

Without --force, declining the confirmation prompt exits with code 0 (no error).

Exit Codes

Code Meaning
0 Setup completed successfully, or user declined to overwrite
1 Error during setup

Examples

Quick setup in current directory

karenina init

Advanced guided setup

karenina init --advanced

Custom working directory

karenina init --dir ~/karenina-workspace

Creates the workspace structure under ~/karenina-workspace/.

Force overwrite existing configuration

karenina init --force

Advanced setup with force overwrite

karenina init --advanced --force