Configuration

Clarissa can be configured via a config file or environment variables. The only required setting is your OpenRouter API key.

API Key Setup

Get your API key from OpenRouter.

Option 1: Interactive Setup (Recommended)

Run the setup command:

clarissa init

This will prompt for your API key and create the config file automatically.

Option 2: Environment Variable

Set your API key as an environment variable:

export OPENROUTER_API_KEY=your_api_key_here

To make this permanent, add it to your shell configuration file (~/.zshrc or ~/.bashrc).

Configuration Options

Settings can be specified in the config file or as environment variables. Environment variables take precedence.

Config Key	Env Variable	Default	Description
`apiKey`	`OPENROUTER_API_KEY`	(required)	Your OpenRouter API key
`model`	`OPENROUTER_MODEL`	`anthropic/claude-sonnet-4`	Default model to use
`maxIterations`	`MAX_ITERATIONS`	`10`	Maximum tool execution iterations per request
`debug`	`DEBUG`	`false`	Enable debug logging

Example Config File

{
  "apiKey": "sk-or-...",
  "model": "anthropic/claude-sonnet-4",
  "maxIterations": 10,
  "debug": false,
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

MCP Servers

Configure MCP (Model Context Protocol) servers to extend Clarissa with additional tools. Servers defined in mcpServers are automatically loaded on startup.

Property	Type	Description
`command`	string	Command to run the MCP server
`args`	string[]	Arguments to pass to the command
`env`	object	Environment variables for the server

Use /mcp to view connected servers and /tools to see available tools.

Available Models

Clarissa supports any model available through OpenRouter. Some popular options include:

anthropic/claude-sonnet-4 - Claude Sonnet 4 (default)
anthropic/claude-opus-4 - Claude Opus 4
openai/gpt-4o - GPT-4o
google/gemini-2.0-flash-001 - Gemini 2.0 Flash
meta-llama/llama-3.3-70b-instruct - Llama 3.3 70B
deepseek/deepseek-chat - DeepSeek Chat

You can switch models at runtime using the /model command. See the full list at OpenRouter Models.

CLI Options

Clarissa accepts command-line arguments for one-shot mode and configuration:

Option	Description
`-c, --continue`	Continue the last session
`-m, --model MODEL`	Use a specific model for this session
`--list-models`	List available models and exit
`--check-update`	Check for available updates
`--debug`	Enable debug output
`-h, --help`	Show help message
`-v, --version`	Show version number

CLI Commands

Clarissa also provides standalone commands:

Command	Description
`clarissa init`	Set up Clarissa with your API key
`clarissa upgrade`	Upgrade to the latest version
`clarissa config`	View current configuration
`clarissa history`	Show one-shot query history

Data Storage

Clarissa stores data in your home directory at ~/.clarissa/:

Path	Description
`~/.clarissa/config.json`	Configuration file (API key, model, etc.)
`~/.clarissa/sessions/`	Saved conversation sessions (JSON files)
`~/.clarissa/memories.json`	Persistent memories across sessions
`~/.clarissa/history.json`	One-shot query history
`~/.clarissa/update-check.json`	Update check cache (24-hour interval)

Debug Mode

Enable debug mode to see detailed logging of API calls and tool executions:

DEBUG=true clarissa

Or use the CLI flag:

clarissa --debug

Next Steps

Now that you're configured, learn about the built-in tools or jump straight to using Clarissa.