---
title: "Configuration"
description: "Configure Caro to match your workflow"
url: "https://caro.sh/docs/configuration"
markdown_url: "https://caro.sh/docs/configuration.md"
lang: "en"
type: "website"
image: "https://caro.sh/og/docs/configuration.png"
---

# Configuration

Caro stores its configuration in a TOML file and can be customized via the config file, command-line flags, or environment variables.

## Configuration File

The configuration file is located at:

- **macOS/Linux**: `~/.config/cmdai/config.toml`
- **Windows**: `%APPDATA%\cmdai\config.toml`

### Example Configuration

```
# ~/.config/cmdai/config.toml

# Default shell for command generation
default_shell = "zsh"

# Safety level: strict, moderate, or permissive
safety_level = "moderate"

# Default model (optional)
default_model = "qwen2.5-coder:3b"

# Logging level: debug, info, warn, error
log_level = "info"

# Maximum cache size for models (in GB)
cache_max_size_gb = 10

# Log rotation period (in days)
log_rotation_days = 7
```

## Interactive Setup

Run the setup wizard to configure Caro interactively:

```
$ caro init
```

To reconfigure an existing installation:

```
$ caro init --force
```

## Configuration Options

### default\_shell

The shell to target when generating commands. If not set, Caro will auto-detect your current shell.

- `bash`
- `zsh`
- `fish`
- `sh` (POSIX)
- `powershell`

### safety\_level

Controls how cautious Caro is with potentially dangerous commands:

- `strict` - Maximum protection, blocks high/critical risk commands
- `moderate` - Balanced protection (default)
- `permissive` - Warnings only, allows all commands with confirmation

### log\_level

Amount of logging output:

- `debug` - Verbose debugging information
- `info` - Normal operation (default)
- `warn` - Warnings and errors only
- `error` - Errors only

## Environment Variables

Override configuration with environment variables. These take precedence over the config file:

```
# Set safety level
export CMDAI_SAFETY_LEVEL=strict

# Set default shell
export CMDAI_DEFAULT_SHELL=bash

# Set log level
export CMDAI_LOG_LEVEL=debug

# Set default model
export CMDAI_DEFAULT_MODEL=qwen2.5-coder:7b

# Set cache size (in GB)
export CMDAI_CACHE_MAX_SIZE_GB=20
```

## Command-Line Overrides

CLI flags override both the config file and environment variables:

```
# Override shell for this command
$ caro --shell bash "list files"

# Override safety level
$ caro --safety strict "delete old files"

# Use a custom config file
$ caro --config-file /path/to/config.toml "list files"
```

## Priority Order

Configuration sources are applied in this order (highest priority first):

1. Command-line flags
2. Environment variables
3. Configuration file
4. Default values

## View Current Configuration

```
$ caro --show-config
Configuration file: /home/user/.config/cmdai/config.toml
Configuration exists: true

Current configuration:
  Default shell: Some(Zsh)
  Safety level: Moderate
  Log level: INFO
  Cache max size: 10 GB
  Log rotation: 7 days
```