Skip to content

configuration.md

Latest commit

 

History

History
380 lines (302 loc) · 9.05 KB

configuration.md

File metadata and controls

380 lines (302 loc) · 9.05 KB

⚙️ Configuration Guide

Complete configuration reference for Codestral CLI.

🔧 Configuration Methods

Codestral CLI supports multiple configuration methods, in order of priority:

  1. Environment Variables (highest priority)
  2. Config File (~/.codestral/config.json)
  3. Command Line Arguments
  4. Built-in Defaults (lowest priority)

🌍 Environment Variables

Required Variables

Variable Description Example
MISTRAL_API_KEY Your Codestral API key export MISTRAL_API_KEY="your-key"

Optional Variables

Variable Description Default Example
MISTRAL_MODEL AI model to use codestral-latest export MISTRAL_MODEL="codestral-2024"
MISTRAL_BASE_URL API endpoint https://codestral.mistral.ai/v1 export MISTRAL_BASE_URL="https://custom.api.com/v1"
MISTRAL_MAX_TOKENS Default response length 2048 export MISTRAL_MAX_TOKENS=1000
MISTRAL_TEMPERATURE Response creativity (0-1) 0.7 export MISTRAL_TEMPERATURE=0.1
MISTRAL_TIMEOUT Request timeout (seconds) 30 export MISTRAL_TIMEOUT=60
PYTHONHTTPSVERIFY SSL verification 1 export PYTHONHTTPSVERIFY=0

Setting Environment Variables

Bash/Zsh (Linux/macOS)

# Temporary (current session)
export MISTRAL_API_KEY="your-api-key"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export MISTRAL_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

Fish Shell

# Temporary
set -x MISTRAL_API_KEY "your-api-key"

# Permanent
set -Ux MISTRAL_API_KEY "your-api-key"

Windows (PowerShell)

# Temporary
$env:MISTRAL_API_KEY="your-api-key"

# Permanent (user level)
[Environment]::SetEnvironmentVariable("MISTRAL_API_KEY", "your-api-key", "User")

Windows (Command Prompt)

rem Temporary
set MISTRAL_API_KEY=your-api-key

rem Permanent
setx MISTRAL_API_KEY "your-api-key"

📁 Configuration File

Location

The config file is stored at: ~/.codestral/config.json

Format

{
  "api_key": "your-api-key-here",
  "model": "codestral-latest",
  "base_url": "https://codestral.mistral.ai/v1",
  "max_tokens": 2048,
  "temperature": 0.7,
  "timeout": 30,
  "show_loader": true,
  "conversation_history_limit": 10
}

Creating Config File

# Create directory
mkdir -p ~/.codestral

# Create config file
cat > ~/.codestral/config.json << EOF
{
  "api_key": "your-api-key-here",
  "model": "codestral-latest",
  "max_tokens": 2000,
  "temperature": 0.1
}
EOF

Configuration Options

Option Type Description Default
api_key string Your Mistral API key required
model string AI model identifier "codestral-latest"
base_url string API endpoint URL "https://codestral.mistral.ai/v1"
max_tokens integer Maximum response tokens 2048
temperature float Response creativity (0.0-1.0) 0.7
timeout integer Request timeout in seconds 30
show_loader boolean Show loading animations true
conversation_history_limit integer Max conversation messages 10

🎛️ Model Configuration

Available Models

  • codestral-latest - Latest Codestral model (recommended)
  • codestral-2024-05-08 - Specific version
  • Custom models (if available in your subscription)

Model Settings

{
  "model": "codestral-latest",
  "temperature": 0.1,     // Lower = more focused, higher = more creative
  "max_tokens": 2048,     // Response length limit
  "top_p": 0.95          // Nucleus sampling parameter
}

Temperature Guide

  • 0.0 - 0.2: Very focused, deterministic responses (good for code)
  • 0.3 - 0.7: Balanced creativity and accuracy (default range)
  • 0.8 - 1.0: High creativity, more variation (good for brainstorming)

🌐 Network Configuration

Proxy Settings

If you're behind a corporate firewall:

# HTTP/HTTPS Proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://proxy.company.com:8080

# With authentication
export HTTP_PROXY=http://username:password@proxy.company.com:8080
export HTTPS_PROXY=https://username:password@proxy.company.com:8080

# No proxy for specific hosts
export NO_PROXY=localhost,127.0.0.1,.company.com

SSL Configuration

# Disable SSL verification (not recommended for production)
export PYTHONHTTPSVERIFY=0

# Custom certificate bundle
export SSL_CERT_FILE=/path/to/your/certificate.pem
export REQUESTS_CA_BUNDLE=/path/to/your/certificate.pem

Timeout Settings

{
  "timeout": 30,           // API request timeout
  "connect_timeout": 10,   // Connection timeout  
  "read_timeout": 60       // Response reading timeout
}

📊 Performance Tuning

Response Size Optimization

{
  "max_tokens": 1000,      // Smaller for faster responses
  "temperature": 0.1,      // Lower for more consistent responses
  "top_p": 0.9            // Reduce for faster generation
}

Conversation Management

{
  "conversation_history_limit": 5,  // Fewer messages for faster processing
  "save_history": false             // Disable history for privacy
}

🔒 Security Configuration

API Key Security

# Use a separate config file with restricted permissions
chmod 600 ~/.codestral/config.json

# Or use environment variables in a secure shell profile
echo 'export MISTRAL_API_KEY="your-key"' >> ~/.profile
chmod 600 ~/.profile

Network Security

# Force HTTPS verification
export PYTHONHTTPSVERIFY=1

# Use specific certificate bundle
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

🎨 UI Configuration

Rich Terminal Features

The CLI automatically detects terminal capabilities. To force settings:

# Disable rich UI
export TERM=dumb

# Force color support
export FORCE_COLOR=1

# Disable color
export NO_COLOR=1

Display Options

{
  "show_loader": true,      // Loading animations
  "show_progress": true,    // Progress indicators
  "markdown_support": true, // Rich markdown rendering
  "syntax_highlighting": true
}

📝 Logging Configuration

Enable Debug Logging

# Environment variable
export CODESTRAL_DEBUG=1

# Or in config file
{
  "debug": true,
  "log_level": "DEBUG",
  "log_file": "~/.codestral/debug.log"
}

Log Levels

  • DEBUG: Detailed debugging information
  • INFO: General information messages
  • WARNING: Warning messages
  • ERROR: Error messages only

🔄 Configuration Validation

Check Current Configuration

# In interactive mode
codestral-cli
config

# Or programmatically
python3 -c "
from codestral_cli.core.config import ConfigManager
config = ConfigManager()
print(config.get_model_info())
"

Validate API Connection

# Test with current config
codestral-cli "test connection"

# Test SSL configuration  
python3 fix_ssl.py

💼 Advanced Configuration

Custom Models

{
  "model": "custom-codestral-model",
  "base_url": "https://your-custom-endpoint.com/v1",
  "api_key": "your-custom-api-key"
}

Multiple Profiles

Create different config files for different use cases:

# Work profile
~/.codestral/work-config.json

# Personal profile  
~/.codestral/personal-config.json

# Use specific config
codestral-cli --config ~/.codestral/work-config.json "work prompt"

Batch Configuration

# Set multiple environment variables
cat > ~/.codestral/env.sh << EOF
export MISTRAL_API_KEY="your-key"
export MISTRAL_MODEL="codestral-latest"  
export MISTRAL_TEMPERATURE=0.1
export MISTRAL_MAX_TOKENS=1500
EOF

# Load configuration
source ~/.codestral/env.sh

🛠️ Configuration Troubleshooting

Common Issues

Config File Not Found

# Check if config directory exists
ls -la ~/.codestral/

# Create if missing
mkdir -p ~/.codestral
echo '{"api_key": "your-key"}' > ~/.codestral/config.json

Invalid JSON Format

# Validate JSON syntax
python3 -m json.tool ~/.codestral/config.json

# Fix common issues
# - Remove trailing commas
# - Use double quotes for strings
# - Escape backslashes in paths

Permission Issues

# Fix permissions
chmod 600 ~/.codestral/config.json
chown $USER ~/.codestral/config.json

Configuration Priority Debug

# Check which config values are being used
from codestral_cli.core.config import ConfigManager
config = ConfigManager()
print(f"API Key: {'Set' if config.api_key else 'Not set'}")
print(f"Model: {config.model}")
print(f"Max Tokens: {config.max_tokens}")
print(f"Temperature: {config.temperature}")

🎯 Best Practices

  1. Keep API keys secure - Use environment variables or restricted file permissions
  2. Use appropriate models - Choose the right model for your use case
  3. Tune temperature - Lower for code generation, higher for creative tasks
  4. Monitor usage - Keep track of API usage and costs
  5. Regular updates - Update configuration as new models become available
  6. Backup configs - Keep backup copies of working configurations