Skip to main content

Configuration Schema Reference

Complete reference for CLI configuration options and file formats

Configuration File Locations

The Lovelace CLI uses a hierarchical configuration system:

~/.lovelace/
├── config.json          # Global configuration
├── workspaces.json       # Workspace definitions
├── credentials.json      # Authentication tokens (encrypted)
├── cache/               # Cached data
└── logs/                # Log files

Global Configuration (config.json)

Schema Overview

json
{
  "$schema": "https://docs.uselovelace.com/schemas/cli-config.json",
  "version": "1.0",
  "user": {
    "id": "user_12345",
    "email": "user@example.com",
    "workspace": "default-workspace"
  },
  "ai": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "workspace": {
    "auto_sync": true,
    "sync_interval": 900,
    "default_context": ["workspace", "git"]
  },
  "agents": {
    "auto_start_daemon": true,
    "max_concurrent": 3,
    "timeout": 300
  },
  "acp": {
    "enabled": true,
    "port": 3000,
    "host": "localhost",
    "require_auth": false
  },
  "mcp": {
    "auto_connect": ["filesystem"],
    "timeout": 30000,
    "max_sessions": 10
  },
  "logging": {
    "level": "info",
    "file": "~/.lovelace/logs/cli.log",
    "max_files": 5,
    "max_size": "10MB"
  },
  "network": {
    "timeout": 30000,
    "retries": 3,
    "proxy": null
  }
}

Configuration Sections

User Settings

json
{
  "user": {
    "id": "user_12345",           // User ID from platform
    "email": "user@example.com",  // User email address
    "workspace": "my-workspace",  // Default workspace
    "timezone": "America/New_York" // User timezone
  }
}

AI Provider Configuration

json
{
  "ai": {
    "provider": "anthropic",        // Primary AI provider
    "fallback_provider": "openai",  // Fallback provider
    "model": "claude-3-5-sonnet",   // Default model
    "temperature": 0.7,             // Response creativity (0-1)
    "max_tokens": 4096,             // Maximum response length
    "timeout": 60000,               // Request timeout (ms)
    "stream": true,                 // Enable streaming responses
    "providers": {
      "anthropic": {
        "api_key_env": "ANTHROPIC_API_KEY",
        "models": ["claude-3-5-sonnet", "claude-3-haiku"],
        "rate_limit": 100
      },
      "openai": {
        "api_key_env": "OPENAI_API_KEY",
        "models": ["gpt-4", "gpt-3.5-turbo"],
        "rate_limit": 60
      }
    }
  }
}

Workspace Configuration

json
{
  "workspace": {
    "auto_sync": true,                    // Automatic synchronization
    "sync_interval": 900,                 // Sync interval (seconds)
    "default_context": ["workspace", "git"], // Default context types
    "exclude_patterns": [                 // Files to exclude from analysis
      "node_modules/**",
      "dist/**",
      "*.log"
    ],
    "max_file_size": "1MB",              // Maximum file size to analyze
    "git_integration": true,             // Enable git integration
    "auto_detect_projects": true         // Auto-detect project types
  }
}

Agent Configuration

json
{
  "agents": {
    "auto_start_daemon": true,    // Start daemon automatically
    "max_concurrent": 3,          // Maximum concurrent executions
    "timeout": 300,               // Default timeout (seconds)
    "memory_limit": "1GB",        // Memory limit per agent
    "cpu_limit": 2,               // CPU cores per agent
    "cache_results": true,        // Cache execution results
    "log_executions": true,       // Log all executions
    "workers": {
      "analysis-worker": {
        "enabled": true,
        "timeout": 600,
        "memory_limit": "2GB"
      },
      "test-worker": {
        "enabled": true,
        "parallel": true
      }
    }
  }
}

ACP Server Configuration

json
{
  "acp": {
    "enabled": true,              // Enable ACP server
    "port": 3000,                 // Server port
    "host": "localhost",          // Server host
    "require_auth": false,        // Require authentication
    "max_connections": 10,        // Maximum concurrent connections
    "timeout": 30000,             // Request timeout (ms)
    "cors": {
      "enabled": true,
      "origins": ["*"]
    },
    "rate_limit": {
      "requests_per_minute": 100,
      "burst": 20
    }
  }
}

MCP Integration Configuration

json
{
  "mcp": {
    "auto_connect": ["filesystem", "git"], // Auto-connect to servers
    "timeout": 30000,                      // Connection timeout (ms)
    "max_sessions": 10,                    // Maximum concurrent sessions
    "retry_attempts": 3,                   // Connection retry attempts
    "servers": {
      "filesystem": {
        "enabled": true,
        "config": {
          "allowed_paths": ["./"],
          "read_only": false
        }
      },
      "database": {
        "enabled": false,
        "config": {
          "connection_string": "postgresql://localhost:5432/dev"
        }
      }
    }
  }
}

Logging Configuration

json
{
  "logging": {
    "level": "info",                    // Log level (debug, info, warn, error)
    "file": "~/.lovelace/logs/cli.log", // Log file path
    "max_files": 5,                     // Maximum log files to keep
    "max_size": "10MB",                 // Maximum file size
    "format": "json",                   // Log format (json, text)
    "timestamp": true,                  // Include timestamps
    "components": {                     // Component-specific levels
      "auth": "debug",
      "network": "warn"
    }
  }
}

Network Configuration

json
{
  "network": {
    "timeout": 30000,           // Request timeout (ms)
    "retries": 3,               // Retry attempts
    "backoff": "exponential",   // Backoff strategy
    "user_agent": "Lovelace-CLI/1.0 (+https://uselovelace.com)",
    "proxy": {
      "http": "http://proxy:8080",
      "https": "https://proxy:8080"
    },
    "ssl": {
      "verify": true,
      "ca_bundle": null
    }
  }
}

Workspace Configuration (.lovelace/config.json)

Per-project configuration file:

json
{
  "project": {
    "name": "my-application",
    "workspace": "development-team",
    "type": "web-application",
    "framework": "react-nextjs",
    "language": "typescript"
  },
  "analysis": {
    "include_patterns": ["src/**/*", "components/**/*"],
    "exclude_patterns": ["node_modules/**", "build/**"],
    "max_depth": 10,
    "follow_symlinks": false
  },
  "integrations": {
    "git": {
      "enabled": true,
      "auto_link_commits": true,
      "branches": ["main", "develop"]
    },
    "package_manager": "npm",
    "ci_cd": "github-actions",
    "testing_framework": "vitest"
  },
  "ai": {
    "context_size": "large",
    "include_tests": true,
    "include_docs": false
  }
}

Environment Variables

Core Variables

VariableDescriptionDefault
LOVELACE_CONFIG_DIRConfiguration directory~/.lovelace
LOVELACE_WORKSPACEDefault workspaceFrom config
LOVELACE_LOG_LEVELLogging levelinfo
LOVELACE_NO_COLORDisable colorsfalse

API Configuration

VariableDescriptionDefault
LOVELACE_API_URLAPI endpointhttps://api.uselovelace.com
LOVELACE_AUTH_URLAuth endpointhttps://auth.uselovelace.com
LOVELACE_AGENTS_URLAgents endpointhttps://agents.uselovelace.com

AI Provider Keys

VariableDescription
ANTHROPIC_API_KEYAnthropic API key
OPENAI_API_KEYOpenAI API key
GOOGLE_API_KEYGoogle AI API key

Development Variables

VariableDescriptionDefault
LOVELACE_DEBUGEnable debug modefalse
LOVELACE_MOCK_APIUse mock APIfalse
LOVELACE_OFFLINEOffline modefalse

Configuration Commands

View Configuration

bash
# Show all configuration
lovelace config show

# Show specific section
lovelace config show --section ai

# Show in different format
lovelace config show --format yaml

Modify Configuration

bash
# Set single value
lovelace config set ai.provider anthropic

# Set nested value
lovelace config set agents.max_concurrent 5

# Set boolean value
lovelace config set workspace.auto_sync true

# Set array value
lovelace config set workspace.default_context workspace,git

Reset Configuration

bash
# Reset all configuration
lovelace config reset

# Reset specific section
lovelace config reset --section ai

# Reset to factory defaults
lovelace config reset --factory

Configuration Validation

Schema Validation

The CLI validates configuration against JSON schemas:

bash
# Validate current configuration
lovelace config validate

# Validate specific file
lovelace config validate --file ~/.lovelace/config.json

# Show validation errors
lovelace config validate --verbose

Common Validation Errors

Invalid AI Provider:

json
{
  "error": "Invalid AI provider",
  "field": "ai.provider",
  "value": "invalid-provider",
  "allowed": ["anthropic", "openai", "google"]
}

Out of Range Value:

json
{
  "error": "Value out of range",
  "field": "ai.temperature",
  "value": 2.0,
  "range": [0, 1]
}

Migration and Upgrades

Configuration Migration

When upgrading CLI versions:

bash
# Check for migration needs
lovelace config migrate --check

# Perform migration
lovelace config migrate

# Backup before migration
lovelace config backup

Backup and Restore

bash
# Create configuration backup
lovelace config backup --output backup.json

# Restore from backup
lovelace config restore --input backup.json

# List available backups
lovelace config backups

Security Considerations

Credential Storage

  • Credentials are encrypted using system keychain
  • API keys stored in separate encrypted file
  • Environment variables preferred for CI/CD

File Permissions

bash
# Recommended permissions
chmod 600 ~/.lovelace/config.json
chmod 600 ~/.lovelace/credentials.json
chmod 700 ~/.lovelace/

Network Security

  • All API communications use HTTPS
  • Certificates validated by default
  • Proxy support for corporate environments

See Also: