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