CLI Reference

📋 CLI Overview

SAM Framework provides a comprehensive command-line interface for all operations. The CLI is designed to be intuitive and handles both interactive agent sessions and administrative tasks.

sam [command] [options]

🚀 Core Commands

`sam run` - Interactive Agent

Start the main SAM agent in interactive mode for natural language blockchain operations.

Usage:

sam run [--session SESSION_ID]
sam [--session SESSION_ID]  # Short form - run is default

Options:

--session, -s: Session ID for conversation context (default: "default")

Examples:

# Start with default session
sam

# Start with custom session
sam --session trading_session

# Short form
sam -s my_session

Interactive Commands: Once in interactive mode, use these slash commands:

| Command | Description | |---------|-------------| | /help, /? | Show available commands | | /tools | List all available tools | | /config | Show current configuration | | /provider | Manage LLM providers | | /settings | Interactive configuration editor | | /clear, /cls | Clear screen | | /clear-context | Clear conversation context | | /compact | Compact conversation history | | /wallet | Show wallet address | | /balance [address] | Check balance for address | | /switch <provider> | Switch LLM provider | | exit, quit, /exit | Exit interactive mode | | ESC | Interrupt current operation | | Ctrl+C | Force exit |

Command Palette: Type / to access the interactive command menu with picker interface.

`sam onboard` - Setup Wizard

Run the interactive setup wizard to configure SAM with optimal defaults.

Usage:

sam onboard

What it configures:

OpenAI API key setup
Solana RPC endpoint selection
Secure private key import
Optional Brave Search API
Automatic encryption key generation
Database initialization

🔐 Key Management

`sam key import` - Import Private Key

Securely import and encrypt your Solana private key using system keyring.

Usage:

sam key import

Process:

Tests system keyring availability
Prompts for user ID (default: "default")
Hidden input for private key
Encrypts key with Fernet
Stores in system keyring
Verifies storage and retrieval

Security Features:

Hidden password input
Automatic encryption before storage
System keyring integration
Retrieval verification

`sam key generate` - Generate Encryption Key

Generate a new Fernet encryption key for secure data encryption.

Usage:

sam key generate

What it does:

Generates cryptographically secure Fernet key
Updates .env file automatically
Applies key to current session
Provides backup instructions

⚙️ Configuration Commands

`sam setup` - Setup Status Check

Check configuration status and validate all required settings.

Usage:

sam setup

Validations Performed:

✅ OpenAI API key presence and format
✅ Fernet encryption key validity
✅ Solana RPC connectivity
✅ Wallet configuration status
✅ Database accessibility
✅ Optional integrations (Brave Search)

`sam health` - System Health Check

Comprehensive system health diagnostics and status reporting.

Usage:

sam health

Health Checks:

Configuration validation
API connectivity testing (OpenAI, Solana RPC)
Database integrity verification
Wallet balance confirmation
Tool availability testing
Memory usage monitoring

`sam tools` - List Available Tools

Display all available tools organized by category.

Usage:

sam tools

Output Categories:

💰 Wallet & Balance (3 tools)
🚀 Pump.fun Trading (4 tools)
🌌 Jupiter DEX (3 tools)
📊 Market Data (4 tools)
🌐 Web Search (2 tools)

🤖 Provider Management

`sam provider list` - List Available Providers

Display all supported LLM providers and their status.

Usage:

sam provider list

Shows:

Available providers (openai, anthropic, xai, openai_compat, local)
Current active provider
Provider capabilities and requirements

`sam provider current` - Show Current Provider

Display detailed information about the currently active LLM provider.

Usage:

sam provider current

Information Displayed:

Provider name and type
Model configuration
API endpoint
Rate limits and quotas
Authentication status

`sam provider switch` - Switch Provider

Switch to a different LLM provider with validation.

Usage:

sam provider switch <provider_name>

Parameters:

provider_name: One of openai, anthropic, xai, openai_compat, local

Process:

Validates provider availability
Checks API key configuration
Tests provider connectivity
Updates configuration
Provides restart instructions

Examples:

sam provider switch anthropic
sam provider switch xai

`sam provider test` - Test Provider Connection

Test the connection and functionality of the current or specified provider.

Usage:

sam provider test [--provider PROVIDER_NAME]

Options:

--provider: Specific provider to test (defaults to current)

Tests Performed:

API connectivity
Authentication validation
Model availability
Tool calling support
Response time measurement

⚙️ Interactive Settings

`sam settings` - Configuration Editor

Launch the interactive configuration editor for runtime settings management.

Usage:

sam settings

Configurable Options:

LLM provider settings
Safety limits and thresholds
Tool enablement toggles
Rate limiting configuration
Logging preferences
Database settings

Features:

Interactive menu system
Input validation
Configuration preview
Automatic backup
Restart requirement detection

🛠️ Maintenance Commands

`sam maintenance` - Database Maintenance

Run database cleanup and optimization tasks.

Usage:

sam maintenance

Maintenance Tasks:

Database vacuum and optimization
Old session cleanup
Index rebuilding
Storage space reclamation
Performance optimization

`sam debug` - Runtime Inspection

Inspect loaded plugins, middlewares, and tool configurations.

Usage:

sam debug

Debug Information:

Loaded plugins and entry points
Active middleware configuration
Registered tools by namespace
Environment variable status
Provider and memory backend details

📋 Command Reference Table

| Command | Description | Category | |---------|-------------|----------| | sam | Start interactive agent | Core | | sam run [--session ID] | Start agent with session | Core | | sam onboard | Run setup wizard | Setup | | sam key import | Import private key securely | Security | | sam key generate | Generate encryption key | Security | | sam provider list | List available LLM providers | Provider Management | | sam provider current | Show current provider | Provider Management | | sam provider switch <name> | Switch to different provider | Provider Management | | sam provider test [--provider NAME] | Test provider connection | Provider Management | | sam settings | Interactive configuration editor | Configuration | | sam setup | Check setup status | Configuration | | sam health | System health check | Monitoring | | sam tools | List available tools | Information | | sam debug | Show plugins and middleware info | Debugging | | sam maintenance | Database maintenance | Maintenance |

🔧 Global Options

Log Level Control

Control logging verbosity across all commands.

Usage:

sam [command] --log-level LEVEL

Available Levels:

DEBUG: Detailed debugging information
INFO: General information (default)
WARNING: Warning messages only
ERROR: Error messages only

Examples:

# Debug mode for troubleshooting
sam --log-level DEBUG

# Minimal logging for production
sam health --log-level WARNING

💡 Usage Patterns

Provider Management Workflow

# Check available providers
sam provider list

# Switch to different provider
sam provider switch anthropic

# Test provider connection
sam provider test

# View current provider details
sam provider current

Development Workflow

# Initial setup
sam onboard

# Configure providers and settings
sam settings

# Development with debug logging
sam --log-level DEBUG

# Test configuration
sam setup

# Inspect runtime state
sam debug

# Check system health
sam health

Production Deployment

# Health check before deployment
sam health

# Run with minimal logging
sam --log-level WARNING

# Regular maintenance
sam maintenance

# Monitor provider performance
sam provider test

Plugin Development

# Test plugin loading
export SAM_PLUGINS="my_plugin"
sam debug

# Verify tool registration
sam tools

# Test plugin functionality
sam --log-level DEBUG

Troubleshooting

# Debug mode for issue investigation
sam --log-level DEBUG setup

# Check tool availability
sam tools

# Inspect plugins and middleware
sam debug

# Test provider connectivity
sam provider test

# Verify configuration
sam setup

🚨 Error Handling

Common Exit Codes

| Code | Meaning | Action | |------|---------|--------| | 0 | Success | No action needed | | 1 | General error | Check error message | | 130 | Keyboard interrupt | User cancelled operation |

Error Messages

Configuration Errors:

❌ OPENAI_API_KEY is required
# Solution: Run sam onboard or set OPENAI_API_KEY in .env

❌ SAM_FERNET_KEY is required for secure storage
# Solution: Run sam key generate

Connectivity Errors:

❌ Failed to connect to Solana RPC
# Solution: Check SAM_SOLANA_RPC_URL or network connectivity

❌ OpenAI API authentication failed
# Solution: Verify OPENAI_API_KEY is valid

Security Errors:

❌ System keyring not available
# Solution: Install keyring dependencies or use environment variables

❌ Private key decryption failed
# Solution: Verify SAM_FERNET_KEY matches encryption key

🎯 Interactive Mode Features

Smart Command Recognition

SAM recognizes various natural language patterns:

# Balance checking
"check my balance"
"show wallet balance"
"get SOL balance"

# Trading commands
"buy 0.01 SOL of BONK"
"sell 50% of my DOGE"
"get swap quote for 1 SOL to USDC"

Context Management

# Start fresh conversation
/clear-context

# Compact conversation history
/compact

# Switch sessions
sam --session new_session

Context Management Features:

Auto-Compaction: Automatically compacts conversations at 80% context usage (80 messages)
Usage Tracking: Real-time display of context window utilization
Smart Compression: Maintains conversation continuity while reducing token usage
Session Isolation: Independent context windows per session

Real-time Feedback

🔄 Spinner animations for long operations
📊 Token usage tracking
🛠️ Tool execution status
⚡ Performance metrics
📈 Context usage percentage display
🤖 Model and wallet status indicators
🔄 Auto-compaction when context reaches 80%

📊 Monitoring & Analytics

Session Statistics

Available in interactive mode via context info:

Context: 15 msgs • Tokens: 2,450 • Requests: 8
model:gpt-4o-mini • ctx:45% (36/80) • wallet:EPjF...TDt1v

Status Display Features:

Model Info: Shows current LLM model (e.g., gpt-4o-mini, claude-3-5-sonnet-latest)
Context Usage: Percentage and absolute count of context window usage
Wallet Address: Shortened wallet address display
Auto-Compaction: Automatic conversation compression at 80% context usage

Health Metrics

sam health

Provides:

API response times
Database performance
Memory usage
Tool availability status

Usage Tracking

OpenAI API token consumption
Tool execution counts
Session duration tracking
Error rate monitoring

🔄 Automation & Scripting

Non-Interactive Usage

# Run with specific session (non-interactive setup required)
echo "check balance" | sam run --session automated

# Configuration validation in scripts
sam setup && echo "Setup OK" || echo "Setup failed"

Environment Variables

# Set log level for all commands
export SAM_LOG_LEVEL=WARNING

# Disable interactive prompts
export SAM_NON_INTERACTIVE=true

🆘 Getting Help

Built-in Help

# General help
sam --help

# Command-specific help
sam run --help
sam key --help

Interactive Help

# In interactive mode
/help        # Show all commands
/tools       # List available tools
/config      # Show current configuration

Troubleshooting Resources

Check Troubleshooting Guide
Review Configuration Guide
Validate setup with sam health

💡 Pro Tips

• Use sam --log-level DEBUG for detailed troubleshooting
• Run sam health regularly to monitor system status
• Use custom sessions with --session for organization
• The setup wizard (sam onboard) configures everything automatically
• Private keys are encrypted and stored securely - never in plain text

CLI Reference

CLI Reference

📋 CLI Overview

🚀 Core Commands

sam run - Interactive Agent

sam onboard - Setup Wizard

🔐 Key Management

sam key import - Import Private Key

sam key generate - Generate Encryption Key

⚙️ Configuration Commands

sam setup - Setup Status Check

sam health - System Health Check

sam tools - List Available Tools

🤖 Provider Management

sam provider list - List Available Providers

sam provider current - Show Current Provider

sam provider switch - Switch Provider

sam provider test - Test Provider Connection

⚙️ Interactive Settings

sam settings - Configuration Editor

🛠️ Maintenance Commands

sam maintenance - Database Maintenance

sam debug - Runtime Inspection

📋 Command Reference Table

🔧 Global Options

Log Level Control

💡 Usage Patterns

Provider Management Workflow

Development Workflow

Production Deployment

Plugin Development

Troubleshooting

🚨 Error Handling

Common Exit Codes

Error Messages

🎯 Interactive Mode Features

Smart Command Recognition

Context Management

Real-time Feedback

📊 Monitoring & Analytics

Session Statistics

Health Metrics

Usage Tracking

🔄 Automation & Scripting

Non-Interactive Usage

Environment Variables

🆘 Getting Help

Built-in Help

Interactive Help

Troubleshooting Resources

💡 Pro Tips

`sam run` - Interactive Agent

`sam onboard` - Setup Wizard

`sam key import` - Import Private Key

`sam key generate` - Generate Encryption Key

`sam setup` - Setup Status Check

`sam health` - System Health Check

`sam tools` - List Available Tools

`sam provider list` - List Available Providers

`sam provider current` - Show Current Provider

`sam provider switch` - Switch Provider

`sam provider test` - Test Provider Connection

`sam settings` - Configuration Editor

`sam maintenance` - Database Maintenance

`sam debug` - Runtime Inspection