Configuration

The config and setup commands manage CLI configuration.

Setup Wizard

First-time configuration wizard that guides you through LLM provider setup for entity extraction and chat.

chaoscypher setup

Option	Description
`--provider, -p {ollama,openai,anthropic,gemini}`	LLM provider (skip selection prompt)
`--vram INTEGER`	VRAM size in GB for Ollama presets
`--non-interactive`	Non-interactive mode (for CI/scripts)
`--test/--no-test`	Test provider connectivity (default: `--test`)
`--force, -f`	Reconfigure even if already configured

Example: Interactive Setup with Ollama

chaoscypher setup
╭──────────────────────────────────────────╮
│ Configure LLM for entity extraction      │
╰──────────────────────────────────────────╯

Choose LLM Provider:

  [1]  Ollama          Local LLM - Free, private, no API key required
  [2]  OpenAI          GPT-4o - Cloud-based, requires API key
  [3]  Anthropic       Claude - Cloud-based, requires API key
  [4]  Google Gemini   Gemini Pro - Cloud-based, requires API key

Select provider [1/2/3/4/q] (1): 1
Ollama URL (http://localhost:11434):
Testing connection... Connected successfully

How much GPU VRAM do you have?

  [1]  16GB  (RTX 4080, 5080)        → qwen3:8b
  [2]  20GB  (RTX 5080 Super)        → qwen3:14b
  [3]  24GB  (RTX 4090, 3090)        → qwen3:30b
  [4]  32GB  (A100, dual GPUs)       → qwen3:32b
  [5]  48GB  (A6000, 2x 4090)        → qwen3:70b
  [6]  96GB  (H100)                  → qwen3:70b
  [7]  128GB (Multi-H100)            → qwen3:405b
  [8]  Custom                        I'll specify models manually

Select VRAM tier [1/2/3/4/5/6/7/8] (3): 3
Applying 24GB VRAM preset...
  Chat model: qwen3:30b
  Extraction model: qwen3:30b-instruct
  Context window: 32768

╭─ ✓ Configuration Complete ───────────────╮
│ Provider       ollama                     │
│ URL            http://localhost:11434      │
│ Chat Model     qwen3:30b                  │
│ Extraction     qwen3:30b-instruct         │
│ Context Window 32768                      │
│ Config File    ~/.config/chaoscypher/...  │
╰──────────────────────────────────────────╯

Next steps:
  chaoscypher source add document.pdf  # Process a document
  chaoscypher chat                     # Start interactive chat

Embeddings

The default embedding provider runs locally on the CPU using sentence-transformers and does not require API keys. Alternative providers (Ollama, OpenAI, Gemini) are also available. The embedding model is configured via embedding.model in settings.yaml.

Quick Setup Examples

# Ollama with 24GB VRAM preset (skip menus)
chaoscypher setup --provider ollama --vram 24

# OpenAI (reads OPENAI_API_KEY from environment)
chaoscypher setup --provider openai

# Non-interactive for CI (auto-detects provider from env vars)
chaoscypher setup --non-interactive

# Re-run setup after initial configuration
chaoscypher setup --force

Providers

Provider	Requirements
Ollama	Local installation, no API key needed
OpenAI	`OPENAI_API_KEY` environment variable
Anthropic	`ANTHROPIC_API_KEY` environment variable
Gemini	`GEMINI_API_KEY` environment variable

Ollama VRAM Presets

When using Ollama, specify --vram to auto-configure optimal models for your hardware.

VRAM	GPUs	Chat Model
16 GB	RTX 4080, 5080	`phi4:14b`
20 GB	RTX A4000, A4500	`phi4:14b`
24 GB	RTX 4090, 3090	`qwen3:30b`
32 GB	RTX 5090	`qwen3:30b`
48 GB	A6000, 2x 4090	`qwen3:30b`
96 GB	RTX 6000 Pro	`gpt-oss:120b`
128 GB	DGX Spark	`gpt-oss:120b`

Config Commands

Show Configuration

Displays all current settings including defaults, config file values, and environment overrides.

chaoscypher config show

Option	Description
`--format, -f {tree,json,yaml}`	Output format (default: `tree`)

Tree format (default)

chaoscypher config show
Configuration
├── lexicon
│   ├── url: http://localhost:3001
│   ├── timeout: 30
│   └── max_retries: 4
├── paths
│   ├── data_dir: /home/user/.local/share/chaoscypher
│   ├── config_dir: /home/user/.config/chaoscypher
│   └── cache_dir: /home/user/.cache/chaoscypher
├── ui
│   ├── color: True
│   ├── output_format: table
│   └── paging: True
└── llm
    ├── provider: ollama
    ├── ollama_url: http://localhost:11434
    └── ollama_chat_model: qwen3:30b

Config file: /home/user/.config/chaoscypher/cli.yaml
Status: exists

JSON format

chaoscypher config show --format json
{
  "lexicon": {
    "url": "http://localhost:3001",
    "timeout": 30,
    "max_retries": 4
  },
  "paths": {
    "data_dir": "/home/user/.local/share/chaoscypher",
    "config_dir": "/home/user/.config/chaoscypher",
    "cache_dir": "/home/user/.cache/chaoscypher"
  },
  "ui": {
    "color": true,
    "output_format": "table",
    "paging": true
  },
  "llm": {
    "provider": "ollama",
    "ollama_url": "http://localhost:11434",
    "ollama_chat_model": "qwen3:30b"
  }
}

YAML format

chaoscypher config show --format yaml
lexicon:
  url: http://localhost:3001
  timeout: 30
  max_retries: 4
paths:
  data_dir: /home/user/.local/share/chaoscypher
  config_dir: /home/user/.config/chaoscypher
  cache_dir: /home/user/.cache/chaoscypher
ui:
  color: true
  output_format: table
  paging: true
llm:
  provider: ollama
  ollama_url: http://localhost:11434
  ollama_chat_model: qwen3:30b

note

YAML output requires PyYAML. If not installed, the command falls back to JSON format automatically.

Get a Value

Retrieve a specific configuration value using dot-separated paths.

chaoscypher config get KEY

Use dot-separated paths for nested values (e.g., lexicon.url, llm.provider, paths.data_dir).

chaoscypher config get llm.provider
ollama

chaoscypher config get lexicon.url
http://localhost:3001

chaoscypher config get paths.data_dir
/home/user/.local/share/chaoscypher

When the key points to a group, the full subtree is returned as JSON:

chaoscypher config get llm
{
  "provider": "ollama",
  "ollama_url": "http://localhost:11434",
  "ollama_chat_model": "qwen3:30b"
}

If the key does not exist:

chaoscypher config get nonexistent.key
Key not found: nonexistent.key

Set a Value

Set a configuration value and save it to the config file.

chaoscypher config set KEY VALUE

Values are automatically converted to the appropriate type (boolean, integer, float, or string):

chaoscypher config set lexicon.timeout 60
Set lexicon.timeout = 60
Saved to: /home/user/.config/chaoscypher/cli.yaml

Type conversion happens automatically:

Input	Converted Type	Converted Value
`"true"`, `"yes"`, `"on"`, `"1"`	`bool`	`True`
`"false"`, `"no"`, `"off"`, `"0"`	`bool`	`False`
`"42"`	`int`	`42`
`"3.14"`	`float`	`3.14`
`"qwen3:30b"`	`str`	`"qwen3:30b"`

chaoscypher config set ui.color false
Set ui.color = False
Saved to: /home/user/.config/chaoscypher/cli.yaml

chaoscypher config set llm.ollama_chat_model "qwen3:14b"
Set llm.ollama_chat_model = qwen3:14b
Saved to: /home/user/.config/chaoscypher/cli.yaml

warning

The set command requires PyYAML. If not installed, the command will print an error with install instructions.

Edit Config File

Open the config file in your default editor. Creates the file with commented defaults if it does not exist.

chaoscypher config edit

Uses $EDITOR or $VISUAL environment variable. Falls back to nano on Linux/macOS and notepad on Windows.

Show Config Path

Display the path to the CLI configuration file.

chaoscypher config path

chaoscypher config path
/home/user/.config/chaoscypher/cli.yaml
Status: exists

If the config file has not been created yet:

chaoscypher config path
/home/user/.config/chaoscypher/cli.yaml
Status: not created yet

Reset to Defaults

Remove the config file to restore all default settings.

chaoscypher config reset

Option	Description
`--force, -f`	Skip confirmation prompt

chaoscypher config reset
Delete /home/user/.config/chaoscypher/cli.yaml? [y/N]: y
Configuration reset to defaults.

Config File Location

Platform	Path
Linux	`~/.config/chaoscypher/cli.yaml`
macOS	`~/.config/chaoscypher/cli.yaml`
Windows	`%APPDATA%\chaoscypher\cli.yaml`

The location can be overridden with the CHAOSCYPHER_CONFIG_DIR environment variable.

Configuration Hierarchy

Settings are resolved in the following order (later sources override earlier ones):

Built-in defaults -- hardcoded in the CLI
Config file -- cli.yaml (if it exists)
Environment variables -- CHAOSCYPHER_* prefixed variables

Environment Variables

All settings can be overridden via environment variables:

Variable	Overrides
`LEXICON_URL`	`lexicon.url`
`CHAOSCYPHER_LEXICON_TIMEOUT`	`lexicon.timeout`
`CHAOSCYPHER_DATA_DIR`	`paths.data_dir`
`CHAOSCYPHER_CONFIG_DIR`	`paths.config_dir`
`CHAOSCYPHER_CACHE_DIR`	`paths.cache_dir`
`CHAOSCYPHER_OUTPUT_FORMAT`	`ui.output_format`
`CHAOSCYPHER_NO_COLOR` / `NO_COLOR`	`ui.color` (set to disable)
`CHAOSCYPHER_LLM_PROVIDER`	`llm.provider`
`CHAOSCYPHER_OLLAMA_URL`	`llm.ollama_url`
`CHAOSCYPHER_OLLAMA_CHAT_MODEL`	`llm.ollama_chat_model`
`CHAOSCYPHER_OLLAMA_EXTRACTION_MODEL`	`llm.ollama_extraction_model`
`OPENAI_API_KEY`	`llm.openai_api_key`
`ANTHROPIC_API_KEY`	`llm.anthropic_api_key`
`GEMINI_API_KEY`	`llm.gemini_api_key`
`CHAOSCYPHER_DATABASE`	`database.current`

Setup Wizard​

Example: Interactive Setup with Ollama​

Quick Setup Examples​

Providers​

Ollama VRAM Presets​

Config Commands​

Show Configuration​

Tree format (default)​

JSON format​

YAML format​

Get a Value​

Set a Value​

Edit Config File​

Show Config Path​

Reset to Defaults​

Config File Location​

Configuration Hierarchy​

Environment Variables​