Configuration

Ripperdoc can be configured through configuration files or environment variables.

Configuration Files

Configuration is loaded in order of precedence:

Global: ~/.ripperdoc.json
Project: .ripperdoc/config.json
Local: .ripperdoc/config.local.json (gitignored)

Project and local configuration override global configuration.

Model Configuration

Basic Model Setup

{
  "model_profiles": {
    "default": {
      "provider": "openai_compatible",
      "model": "deepseek-chat",
      "api_key": "YOUR_DEEPSEEK_KEY",
      "api_base": "https://api.deepseek.com",
      "max_tokens": 4096,
      "temperature": 0.0
    }
  },
  "model_pointers": {
    "main": "default",
    "quick": "default"
  }
}

Multiple Models

You can define multiple model profiles:

{
  "model_profiles": {
    "default": {
      "provider": "openai_compatible",
      "model": "deepseek-chat",
      "api_key": "YOUR_DEEPSEEK_KEY",
      "api_base": "https://api.deepseek.com"
    },
    "reasoner": {
      "provider": "openai_compatible",
      "model": "deepseek-reasoner",
      "api_key": "YOUR_DEEPSEEK_KEY",
      "api_base": "https://api.deepseek.com",
      "thinking_mode": "deepseek"
    },
    "local": {
      "provider": "openai_compatible",
      "model": "llama3.2",
      "api_base": "http://localhost:11434/v1",
      "api_key": null
    }
  },
  "model_pointers": {
    "main": "default",
    "quick": "reasoner"
  }
}

Switch between profiles using the /models command or --model flag (use the profile name from model_profiles):

ripperdoc --model reasoner

Model Profile Fields

Field	Description	Required
`provider`	Provider type	Yes
`model`	Model identifier	Yes
`api_key`	API key (or use env var)	Provider-specific
`api_base`	API base URL	Provider-specific
`auth_token`	Bearer token authentication	No
`max_tokens`	Maximum output tokens	No
`temperature`	Sampling temperature	No
`thinking_mode`	Extended thinking mode	No
`max_input_tokens`	Maximum input tokens	No
`max_output_tokens`	Maximum output tokens	No
`openai_tool_mode`	Tool calling mode for OpenAI	No
`supports_vision`	Override image/vision support (true/false)	No
`input_cost_per_million_tokens`	Cost tracking (input)	No
`output_cost_per_million_tokens`	Cost tracking (output)	No

Set supports_vision to true if your model supports image input and auto-detection does not pick it up.

Provider Options

Provider	Required Config	Description
`openai_compatible`	`api_base`, `model`	Any OpenAI-compatible API
`anthropic`	`api_key`	Anthropic Claude
`gemini`	`api_key`	Google Gemini
`volcengine`	`api_key`, `model`	Volcengine Seed 2.0
`aliyun`	`api_key`, `model`	Alibaba Cloud (Aliyun)
`stepfun`	`api_key`, `model`	StepFun (阶跃星辰)
`nvidia`	`api_key`, `model`	NVIDIA API endpoints

Provider Preset Mode

For simplified model configuration, you can use the provider preset mode:

ripperdoc --model claude-sonnet  # Auto-detects provider from model name

The system will automatically detect the correct provider and configuration based on the model name.

Authentication Options

{
  "model_profiles": {
    "with_api_key": {
      "provider": "openai_compatible",
      "api_key": "sk-xxx",
      "api_base": "https://api.example.com/v1",
      "model": "model-name"
    },
    "with_bearer_token": {
      "provider": "openai_compatible",
      "auth_token": "your-bearer-token",
      "api_base": "https://api.example.com/v1",
      "model": "model-name"
    }
  }
}

Thinking Mode

For models that support extended thinking (DeepSeek, Claude with extended thinking):

{
  "model_profiles": {
    "reasoning": {
      "provider": "openai_compatible",
      "model": "deepseek-reasoner",
      "api_key": "YOUR_DEEPSEEK_KEY",
      "api_base": "https://api.deepseek.com",
      "thinking_mode": "deepseek"
    }
  }
}

Thinking mode options:

Mode	Description
`none`	Disable extended thinking (default)
`deepseek`	DeepSeek-style thinking
`anthropic`	Anthropic-style thinking (Claude)
`openrouter`	OpenRouter compatible mode
`qwen`	Qwen style thinking
`gemini_openai`	Gemini OpenAI compatible mode
`openai`	OpenAI style thinking

When not set, the system will infer the correct thinking mode based on the provider automatically.

OpenAI Tool Mode

Control how tools are presented to OpenAI-compatible models:

{
  "model_profiles": {
    "custom": {
      "provider": "openai_compatible",
      "model": "model-name",
      "openai_tool_mode": "native"
    }
  }
}

Options:

native - Use OpenAI native tool calling
text - Use text-based tool descriptions

Cost Tracking

Track token costs per model:

{
  "model_profiles": {
    "expensive": {
      "provider": "openai_compatible",
      "model": "gpt-4",
      "api_key": "YOUR_KEY",
      "api_base": "https://api.openai.com/v1",
      "input_cost_per_million_tokens": 30.0,
      "output_cost_per_million_tokens": 60.0
    }
  }
}

Custom API Endpoints

For OpenAI-compatible APIs:

{
  "model_profiles": {
    "custom": {
      "provider": "openai_compatible",
      "api_base": "https://your-api-endpoint.com/v1",
      "api_key": "YOUR_CUSTOM_KEY",
      "model": "your-model-name"
    }
  },
  "model_pointers": {
    "main": "custom",
    "quick": "custom"
  }
}

Permission Settings

{
  "allowed_tools": ["Read", "Glob", "Grep", "LS", "Edit", "Bash"],
  "bash_allow_rules": [
    {"pattern": "npm *", "description": "Allow npm"}
  ],
  "bash_ask_rules": [
    {"pattern": "terraform *", "description": "Always ask before terraform"}
  ],
  "bash_deny_rules": [
    {"pattern": "rm -rf /", "description": "Block dangerous"}
  ]
}

See Permissions for detailed configuration.

Theme Configuration

Ripperdoc includes a built-in theme system for customizing the CLI appearance. Configure your preferred theme in the global config:

{
  "theme": "dark"
}

Available Themes

Theme	Description
`dark`	Default dark theme with cyan accents
`light`	Light theme for bright terminals
`monokai`	Monokai-inspired color scheme
`dracula`	Dracula color scheme
`solarized_dark`	Solarized dark color scheme
`nord`	Arctic, bluish color scheme

Switch themes at runtime using the /themes command:

> /themes              # Show current theme and list available
> /themes light        # Switch to light theme
> /themes preview nord # Preview nord theme colors

CLI Options

Option	Description
`--model NAME`	Use a specific model profile
`--yolo`	Skip permission prompts
`--verbose`	Enable verbose output
`--max-thinking-tokens N`	Set max thinking tokens
`-c`, `--continue`	Continue last session
`-p`, `--prompt TEXT`	Non-interactive prompt

Environment Variables

API keys can be provided in the config file. If you want to configure via env vars, Ripperdoc only reads RIPPERDOC_* variables (provider-specific vars like OPENAI_API_KEY are not used).

These variables override config values in memory for the current session (they are not persisted to disk). If no profile exists, set at least RIPPERDOC_MODEL, RIPPERDOC_PROTOCOL, or RIPPERDOC_BASE_URL so Ripperdoc can build a profile.

Variable	Description
`RIPPERDOC_BASE_URL`	API base URL override (`api_base`)
`RIPPERDOC_API_KEY`	API key override (`api_key`)
`RIPPERDOC_AUTH_TOKEN`	Auth token override (`auth_token`)
`RIPPERDOC_MODEL`	Model name override
`RIPPERDOC_SMALL_FAST_MODEL`	Model name for the `quick` pointer
`RIPPERDOC_PROTOCOL`	Protocol family (`anthropic`, `openai_compatible`, `gemini`)

Other environment variables

Variable	Description
`RIPPERDOC_MAX_RETRIES`	Max API retries (default: 10)
`RIPPERDOC_API_TIMEOUT`	API timeout in seconds (default: 120)

See Environment Variables for a complete list.