Instruction file imported from JZ1101/tooly (.github/instructions/cli-configuration.instructions.md). Copyright stays with the author.

CLI Configuration

The uses a flexible, multi-layered configuration system that allows you to customize behavior through various methods. This guide covers all configuration options and methods.

Configuration Hierarchy

Configurations are applied in the following order (later sources override earlier ones):

1. Built-in defaults - Predefined sensible defaults
2. Global config file - ~/.spoon/config.json or ~/.config/spoon/config.json
3. Project config file - ./config.json in current directory
4. Environment variables - Shell environment variables
5. Command-line arguments - Flags and options passed to commands

Configuration File

The primary configuration method is through a JSON configuration file. Create config.json in your project root or home directory.

Basic Configuration

{
  "default_agent": "react",
  "api_keys": {
    "openai": "[REDACTED openai-key]",
    "anthropic": "[REDACTED openai-key]"
  },
  "agents": {
    "my_agent": {
      "class_name": "SpoonReactAI",
      "description": "My custom agent",
      "config": {
        "llm_provider": "openai",
        "model_name": "gpt-4",
        "temperature": 0.7
      },
      "tools": ["web_search", "calculator"]
    }
  }
}

Advanced Configuration

{
  "default_agent": "react",
  "api_keys": {
    "openai": "sk-...",
    "anthropic": "sk-ant-...",
    "deepseek": "sk-...",
    "gemini": "your-gemini-key"
  },
  "agents": {
    "react": {
      "class_name": "SpoonReactAI",
      "description": "Standard React agent",
      "aliases": ["r"],
      "config": {
        "llm_provider": "anthropic",
        "model_name": "claude-3-sonnet-20240229",
        "temperature": 0.7,
        "max_tokens": 4000
      },
      "tools": ["web_search", "file_operations", "calculator"]
    },
    "mcp_agent": {
      "class_name": "SpoonReactMCP",
      "description": "Agent with MCP support",
      "config": {
        "llm_provider": "openai",
        "model_name": "gpt-4-turbo-preview"
      },
      "mcp_servers": ["filesystem", "github"]
    }
  },
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "slack": {
      "command": "uvx",
      "args": ["mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-..."
      }
    }
  },
  "llm": {
    "fallback_chain": ["anthropic", "openai", "deepseek"],
    "timeout": 30,
    "retry_attempts": 3
  },
  "logging": {
    "level": "INFO",
    "file": "spoon_cli.log",
    "max_file_size": "10MB",
    "backup_count": 5
  }
}

Environment Variables

Environment variables provide an alternative way to configure sensitive information like API keys.

LLM Provider API Keys

# Primary LLM providers
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export DEEPSEEK_API_KEY="sk-..."

# Additional providers
export GEMINI_API_KEY="AIza..."
export OPENROUTER_API_KEY="sk-or-v1-..."
export TAVILY_API_KEY="tvly-..."

Blockchain Configuration

export PRIVATE_KEY="0x..."
export RPC_URL="https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
export CHAIN_ID="1"
export SCAN_URL="https://etherscan.io"

Application Settings

export SPOON_CLI_CONFIG_FILE="/path/to/custom/config.json"
export SPOON_CLI_LOG_LEVEL="DEBUG"
export SPOON_CLI_DEFAULT_AGENT="my_agent"

Configuration Management Commands

The CLI provides built-in commands to manage configuration:

View Configuration

# Start spoon-cli and run:
# Show all configuration
config

# Show specific key
config api_keys.openai

# Show LLM status
llm-status

Modify Configuration

# Start spoon-cli and run:
# Set API key
config api_key openai "sk-your-key"

# Set configuration value
config default_agent "my_custom_agent"

# Set nested configuration
config llm.timeout 60

Configuration Validation

# Start spoon-cli and run:
# Validate current configuration
validate-config

# Check for migration needs
check-config

# Migrate legacy configuration
# Start spoon-cli and run:
migrate-config

Configuration Sections

Agents Configuration

Define custom agents with specific configurations:

{
  "agents": {
    "crypto_trader": {
      "class_name": "SpoonReactAI",
      "description": "Cryptocurrency trading assistant",
      "config": {
        "llm_provider": "anthropic",
        "model_name": "claude-3-sonnet-20240229",
        "temperature": 0.3,
        "max_tokens": 2000
      },
      "tools": [
        "crypto_price_lookup",
        "dex_swap",
        "wallet_balance",
        "market_data"
      ]
    }
  }
}

MCP Servers Configuration

Configure Model Context Protocol servers for extended capabilities:

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {}
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/repo"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

LLM Configuration

Configure LLM provider settings and fallback chains:

{
  "llm": {
    "default_provider": "anthropic",
    "fallback_chain": ["anthropic", "openai", "deepseek"],
    "timeout": 30,
    "retry_attempts": 3,
    "providers": {
      "openai": {
        "base_url": null,
        "organization": null
      },
      "anthropic": {
        "max_tokens": 4096
      }
    }
  }
}

Configuration Profiles

Use different configurations for different environments:

{
  "profiles": {
    "development": {
      "default_agent": "debug_agent",
      "llm": {
        "timeout": 60,
        "retry_attempts": 5
      }
    },
    "production": {
      "default_agent": "production_agent",
      "logging": {
        "level": "WARNING"
      }
    }
  }
}

Activate a profile:

export SPOON_CLI_PROFILE="production"

# Then start spoon-cli with the profile active

Configuration File Locations

The CLI searches for configuration files in the following order:

1. Project-specific: ./config.json
2. User-specific: ~/.spoon/config.json
3. System-wide: /etc/spoon/config.json
4. XDG Base Directory: ~/.config/spoon/config.json

Security Best Practices

API Keys Management

1. Never commit API keys to version control
2. Use environment variables for sensitive data
3. Rotate keys regularly
4. Use different keys for different environments

File Permissions

# Set restrictive permissions on config files
chmod 600 config.json
chmod 600 .env

Environment Separation

Use different configurations for different environments:

# Development
cp config.json config.dev.json
export SPOON_CLI_CONFIG_FILE="config.dev.json"

# Production
cp config.json config.prod.json
export SPOON_CLI_CONFIG_FILE="config.prod.json"

Troubleshooting Configuration

Common Issues

1. Configuration not loading

Start spoon-cli and run:

validate-config

Check file syntax and permissions

2. **API keys not working**
```bash
# Start spoon-cli and run:
llm-status
# Verify key format and validity

3. MCP servers not connecting

Start spoon-cli and run:

validate-config --check-servers

Check server commands and environment variables

### Debug Configuration

Enable debug logging to troubleshoot configuration issues:

```bash
export SPOON_CLI_DEBUG=1
# Start spoon-cli and run:
config

Next Steps

After configuring :

• Basic Usage - Learn basic CLI operations
• Advanced Features - Explore advanced capabilities
• Troubleshooting - Solve common issues