Skip to main content
TLDR: ahvn setup is all you need.
AgentHeaven stores its configuration in a versioned SQLite database. We interact with it through the ahvn config subcommand (aliased ahvn cfg), using dot-separated key paths like llm.providers.openrouter.api_key.

​
1. Initialization

Run ahvn setup once after installation to initialize the ahvn under user home (~/.ahvn/) and create the default config files. 
ahvn setup [--reset/-r]
Using --reset will overwrite existing configuration files and clean up any existing data. Use with caution.

​
2. Config Inspection

ahvn config show (aliased ahvn cfg show or ahvn cfg ls) prints the full merged config as YAML. Pass a dot-separated key path to inspect a specific value: 
# Show the full merged config
ahvn cfg show

# Show a specific value
ahvn cfg show llm.default_preset
#   # sys
ahvn cfg show llm.default_provider
#   # openrouter

# Show a nested section
ahvn cfg show llm.presets.sys
#   # desc: Ahvn's default system preset, suitable for general-purpose use cases. Moderate
#   #     intelligence with fast response time.
#   # model: dsv3
ahvn cfg show llm.providers.openrouter
#   # backend: openrouter
#   # api_key: <OPENROUTER_API_KEY>
#   # api_base: https://openrouter.ai/api/v1

​
3. Config Editing

ahvn config set writes a single value. Values are auto-typed — booleans, integers, and strings are inferred automatically: 
# Enable debug mode
ahvn cfg set core.debug true
ahvn cfg set core.debug false

# Set the LLM API key
ahvn cfg set llm.providers.openrouter.api_key "sk-or-v1-..."

# Set ahvn language (to English)
ahvn cfg set prompts.lang "en"
ahvn config unset (aliased ahvn cfg unset, ahvn cfg rm or ahvn cfg del) removes a key from the current config (which is different from setting it to null or an empty string). Unsetting a key causes it to fall back to the default value if available: 
ahvn cfg show core.http_proxy
# null

ahvn cfg unset core.http_proxy
ahvn cfg show core.http_proxy
# ⚠ Key "core.http_proxy" not found.

ahvn cfg set core.http_proxy null
ahvn cfg show core.http_proxy
# null

​
4. Edit Config in Editor

For bulk edits, ahvn config edit opens the current config in the system editor (env $EDITOR) as a temporary YAML file. Changes are written back to the database on save: 
ahvn cfg edit
On Windows with no $EDITOR set, notepad opens. On macOS and Linux, nano is likely the fallback.

​
Further Exploration

Next step:
Configuration references: