spoon-cli

SpoonAI command-line interface for building and running AI agents with MCP (Model Context Protocol) support. Provides rich functionality including AI agent interaction, chat history management, cryptocurrency operations, and document loading.

Installation

From PyPI (Recommended)

pip install spoon-cli

From Source (Development)

Clone the repository and navigate to the CLI directory:

git clone <repository-url>
cd spoon-cli

Install in editable mode:

pip install -e .

Configuration

The spoon-cli uses a unified configuration system that supports multiple configuration sources with the following priority order (highest to lowest):

Command-line arguments
Environment variables
JSON configuration file (config.json)
Default values

Configuration File Setup

Create a config.json file in your project root or home directory:

{
  "agents": {
    "my_agent": {
      "class_name": "SpoonReactAI",
      "description": "My custom agent",
      "aliases": ["ma"],
      "config": {
        "llm_provider": "openai",
        "model_name": "gpt-4.1",
        "temperature": 0.7
      },
      "tools": [
        {
          "name": "tavily_search",
          "type": "mcp",
          "mcp_server": {
            "command": "npx",
            "args": ["-y", "tavily-mcp"],
            "env": {
              "TAVILY_API_KEY": "your-tavily-api-key"
            }
          }
        },
        {
          "name": "crypto_powerdata_cex",
          "type": "builtin"
        },
        "calculator"
      ]
    }
  },
  "default_agent": "my_agent",
  "api_keys": {
    "openai": "sk-your-openai-key-here",
    "anthropic": "sk-ant-your-anthropic-key-here"
  },
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/git/repo"]
    }
  }
}

Environment Variables

Set required API keys before starting:

# Required for web search (Tavily MCP)
export TAVILY_API_KEY="your-tavily-api-key"

# Required for LLM functionality
export OPENAI_API_KEY="your-openai-api-key"

# Optional: Additional LLM providers
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export DEEPSEEK_API_KEY="your-deepseek-key"
export GEMINI_API_KEY="your-gemini-key"

# Optional: Blockchain operations
export PRIVATE_KEY="your-wallet-private-key"
export RPC_URL="https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
export CHAIN_ID="1"

# Optional: Debug mode
export DEBUG=true
export LOG_LEVEL=debug

# Optional: Social media integration
export TELEGRAM_BOT_TOKEN="your-telegram-bot-token"

Configuration Commands

The CLI provides built-in commands to manage configuration:

# Show current configuration
spoon-cli config

# Get specific configuration value
spoon-cli config api_keys.openai

# Set configuration value
spoon-cli config api_keys.openai "sk-your-key"

# Set API key (shorthand)
spoon-cli config api_key openai "sk-your-key"

# Reload configuration
spoon-cli reload-config

# Validate configuration
spoon-cli validate-config

# Check configuration migration status
spoon-cli check-config

# Migrate legacy configuration
spoon-cli migrate-config

MCP Server Configuration

Configure MCP servers for extended tool capabilities. SpoonOS supports stdio and URL-based (SSE/WebSocket) MCP servers.

Method	Use Case	Configuration Example
`npx`	Node.js packages	`"command": "npx", "args": ["-y", "package-name"]`
`python`	Python scripts	`"command": "python", "args": ["server.py"]`
`uvx`	uvx-installed CLIs	`"command": "uvx", "args": ["package-or-entrypoint"]`
`http`	HTTP/HTTPS	`"url": "https://example.com/mcp", "transport": "http"`
`sse`	HTTP/HTTPS SSE	`"url": "https://example.com/mcp", "transport": "sse"`

{
  "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_your_token_here"
      }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "your-tavily-api-key"
      }
    }
  }
}

MCP-Enabled Agent Example

{
  "agents": {
    "search_agent": {
      "class": "SpoonReactMCP",
      "description": "Search agent with web search capabilities",
      "aliases": ["search", "web"],
      "tools": [
        {
          "name": "tavily_search",
          "type": "mcp",
          "description": "Web search using Tavily API",
          "mcp_server": {
            "command": "npx",
            "args": ["-y", "tavily-mcp"],
            "env": {
              "TAVILY_API_KEY": "your-tavily-api-key"
            }
          }
        },
        {
          "name": "crypto_powerdata_cex",
          "type": "builtin",
          "description": "Cryptocurrency market data from centralized exchanges"
        }
      ]
    }
  }
}

Usage

Quick Start

# Start interactive CLI
spoon-cli

# Or for development
python -m spoon_cli

Available Agents

The CLI includes these built-in agents:

Agent	Aliases	Type	MCP Support	Description
`react`	`spoon_react`	SpoonReactAI	❌	Standard blockchain analysis agent
`spoon_react_mcp`	-	SpoonReactMCP	✅	MCP-enabled blockchain agent

Note: Additional agents can be configured in config.json.

Loading Agents

# List all available agents
spoon-cli list-agents

# Load built-in agent by name
spoon-cli load-agent react
spoon-cli load-agent spoon_react_mcp

# Load agent by alias
spoon-cli load-agent spoon_react

Basic Usage Examples

# Start interactive CLI
spoon-cli

# Load specific agent
spoon-cli load-agent react

# Start chat with default agent
spoon-cli action chat

Example: Using Search Agent

After configuring the search agent with Tavily MCP and crypto tools, you can use it for comprehensive market analysis:

# Load the search agent
spoon-cli load-agent search_agent

# Ask about market analysis combining web search and crypto data
spoon-cli action chat
# Then type: "Analyze the current Bitcoin market sentiment and provide the latest price data from major exchanges"

# Ask about specific cryptocurrency news
# "Search for recent news about Ethereum layer 2 solutions and their market impact"

Available Commands

Core Commands

Command	Aliases	Description
`help`	`h`, `?`	Display help information
`exit`	`quit`, `q`	Exit the CLI
`system-info`	`sysinfo`, `status`, `info`	Display comprehensive system information, environment status, and health checks

Agent Management

Command	Aliases	Description
`load-agent <name>`	`load`	Load an agent with the specified name
`list-agents`	`agents`	List all available agents
`reload-config`	`reload`	Reload the current agent's configuration

Chat Management

Command	Aliases	Description
`action <action>`	`a`	Perform a specific action using the current agent
`new-chat`	`new`	Start a new chat (clear history)
`list-chats`	`chats`	List available chat history records
`load-chat <ID>`	-	Load a specific chat history record

Configuration Management

Command	Aliases	Description
`config`	`cfg`, `settings`	Configure settings (such as API keys)
`migrate-config`	`migrate`	Migrate legacy configuration to new unified format
`check-config`	`check-migration`	Check if configuration needs migration
`validate-config`	`validate`	Validate current configuration and check for issues

LLM Provider Management

Command	Aliases	Description
`list-providers`	`providers`	List all available LLM providers
`set-provider <provider>`	`provider`	Set the default LLM provider
`test-provider <provider>`	`test`	Test connectivity to a specific provider
`llm-status`	`llm`	Show LLM provider configuration and availability
`provider-status`	`status`	Show health status of all providers
`provider-stats <provider>`	`stats`	Show performance statistics for a provider
`config provider <name> <key> <value>`	-	Configure provider-specific settings

Blockchain Operations

Command	Aliases	Description
`transfer <address> <amount> <token>`	`send`	Transfer tokens to a specified address
`swap <source_token> <target_token> <amount>`	-	Exchange tokens using an aggregator
`token-info <address>`	`token`	Get token information by address
`token-by-symbol <symbol>`	`symbol`	Get token information by symbol

Document Management

Command	Aliases	Description
`load-docs <directory_path>`	`docs`	Load documents from the specified directory to the current agent

Toolkit Management

Command	Aliases	Description
`list-toolkit-categories`	`toolkit-categories`, `categories`	List all available toolkit categories
`list-toolkit-tools <category>`	`toolkit-tools`	List tools in a specific category
`load-toolkit-tools <categories>`	`load-tools`	Load toolkit tools from specified categories
`tool-status`	-	Check tool loading status and diagnose issues

Social Integration

Command	Aliases	Description
`telegram`	`tg`	Start the Telegram client

LLM Provider Management Examples

List Available Providers

spoon-cli list-providers

Output:

Available LLM providers:
✅ openai (gpt-4.1) - Healthy
✅ anthropic (claude-sonnet-4-20250514) - Healthy
❌ gemini (gemini-2.5-pro) - Unhealthy
Default provider: openai

Switch Default Provider

spoon-cli set-provider anthropic
# Output: Default LLM provider set to: anthropic

Test Provider Connectivity

spoon-cli test-provider openai

Output:

Testing OpenAI provider...
✅ Connection successful
Model: gpt-4.1
Response time: 1.2s

View Provider Statistics

spoon-cli provider-stats openai

Output:

OpenAI Provider Statistics:
Total requests: 1,247
Successful requests: 1,198 (96.1%)
Average response time: 2.3s
Rate limit hits: 12
Last error: 2 hours ago

Configure Provider Settings

# Configure OpenAI model
spoon-cli config provider openai model gpt-4.1

# Configure Anthropic temperature
spoon-cli config provider anthropic temperature 0.7

# Configure OpenAI max tokens
spoon-cli config provider openai max_tokens 8192

Interactive Examples

Basic Configuration Setup

# 1. Check current configuration
spoon-cli config

# 2. Set API keys
spoon-cli config api_key openai "sk-your-key-here"
spoon-cli config api_key anthropic "sk-ant-your-key-here"

# 3. View current configuration
spoon-cli config

LLM Provider Management

# 1. List available providers
spoon-cli list-providers

# 2. Test OpenAI connectivity
spoon-cli test-provider openai

# 3. Switch to Anthropic as default
spoon-cli set-provider anthropic

# 4. View provider statistics
spoon-cli provider-stats anthropic

Agent and Chat Management

# 1. List available agents
spoon-cli list-agents

# 2. Load React agent
spoon-cli load-agent react

# 3. Start chat session
spoon-cli action chat

# 4. Inside chat, you can interact with the agent
# Type: "Hello, can you help me analyze some cryptocurrency data?"
# Type: "What cryptocurrencies are you familiar with?"

Cryptocurrency Operations

# 1. Load agent with crypto tools
spoon-cli load-agent react
spoon-cli load-toolkit-tools crypto

# 2. Get token information
spoon-cli token-by-symbol SPO

# 3. Get centralized exchange market data
spoon-cli action chat
# Then type: "Get the latest Bitcoin price and volume data from major CEXs"

# 4. Transfer tokens (requires PRIVATE_KEY)
spoon-cli transfer 0x123... 0.1 SPO

# 5. Swap tokens (requires PRIVATE_KEY)
spoon-cli swap ETH USDC 1.0

Advanced Configuration

Custom Agent Definition

Define custom agents in your config.json:

{
  "agents": {
    "crypto_analyzer": {
      "class_name": "SpoonReactAI",
      "description": "Cryptocurrency analysis agent with web search",
      "config": {
        "llm_provider": "anthropic",
        "model_name": "claude-3-sonnet-20240229",
        "temperature": 0.3,
        "max_tokens": 4000
      },
      "tools": [
        {
          "name": "tavily_search",
          "type": "mcp",
          "mcp_server": {
            "command": "npx",
            "args": ["-y", "tavily-mcp"],
            "env": {
              "TAVILY_API_KEY": "your-tavily-api-key"
            }
          }
        },
        {
          "name": "crypto_powerdata_cex",
          "type": "builtin",
          "description": "Cryptocurrency market data from centralized exchanges"
        }
      ]
    }
  }
}

MCP Integration

Enable MCP servers for enhanced capabilities:

{
  "agents": {
    "mcp_agent": {
      "class_name": "SpoonReactMCP",
      "description": "Agent with MCP protocol support for web search and crypto data",
      "tools": [
        {
          "name": "tavily_search",
          "type": "mcp",
          "mcp_server": {
            "command": "npx",
            "args": ["-y", "tavily-mcp"],
            "env": {
              "TAVILY_API_KEY": "your-tavily-api-key"
            }
          }
        },
        {
          "name": "crypto_powerdata_cex",
          "type": "builtin",
          "description": "Cryptocurrency market data from centralized exchanges"
        }
      ]
    }
  }
}

Environment-Specific Configuration

Use different configurations for different environments:

{
  "development": {
    "agents": { ... },
    "api_keys": { ... }
  },
  "production": {
    "agents": { ... },
    "api_keys": { ... }
  }
}

Troubleshooting

Common Issues

Missing Dependencies
```
pip install spoon-cli --upgrade
```

Configuration Not Found

spoon-cli check-config
spoon-cli migrate-config

API Key Issues

spoon-cli llm-status
# Set missing keys
spoon-cli config api_key openai "your-key"

Tool Loading Problems

spoon-cli tool-status
spoon-cli reload-config

MCP Server Issues

spoon-cli validate-config --check-servers

Debug Mode

Enable debug logging:

export SPOON_CLI_DEBUG=1
spoon-cli

Health Check

Run comprehensive health check:

spoon-cli system-info

Development

Setting up Development Environment

# Clone and setup
git clone <repo-url>
cd spoon-cli

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
spoon_cli		spoon_cli
tests		tests
.bumpversion.cfg		.bumpversion.cfg
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

XSpoonAi/spoon-cli

Folders and files

Latest commit

History

Repository files navigation

spoon-cli

Installation

From PyPI (Recommended)

From Source (Development)

Configuration

Configuration File Setup

Environment Variables

Configuration Commands

MCP Server Configuration

MCP-Enabled Agent Example

Usage

Quick Start

Available Agents

Loading Agents

Basic Usage Examples

Example: Using Search Agent

Available Commands

Core Commands

Agent Management

Chat Management

Configuration Management

LLM Provider Management

Blockchain Operations

Document Management

Toolkit Management

Social Integration

LLM Provider Management Examples

List Available Providers

Switch Default Provider

Test Provider Connectivity

View Provider Statistics

Configure Provider Settings

Interactive Examples

Basic Configuration Setup

LLM Provider Management

Agent and Chat Management

Cryptocurrency Operations

Advanced Configuration

Custom Agent Definition

MCP Integration

Environment-Specific Configuration

Troubleshooting

Common Issues

Debug Mode

Health Check

Development

Setting up Development Environment

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Uh oh!

Languages

Packages