spotinfo

Command-line tool for AWS EC2 Spot Instance exploration with placement score analysis

spotinfo is a powerful CLI tool and Model Context Protocol (MCP) server that provides comprehensive AWS EC2 Spot Instance information, including real-time placement scores, pricing data, and interruption rates. Perfect for DevOps engineers optimizing cloud infrastructure costs.

Key Features

🎯 AWS Spot Placement Scores

• Real-time placement scores (1-10 scale) for launch success probability
• Regional and AZ-level analysis with visual indicators (🟢🟡🔴)
• Smart contextual scoring - scores reflect entire request success likelihood
• Freshness tracking with cache optimization

🔍 Advanced Filtering & Analysis

• Regex-powered instance type matching (t3.*, ^(m5|c5)\.(large|xlarge)$)
• Multi-dimensional filtering by vCPU, memory, price, regions, and placement scores
• Cross-region comparison with --region all support
• Flexible sorting by price, reliability, savings, or placement scores

📊 Multiple Output Formats

• Visual formats: Table with emoji indicators, plain text
• Data formats: JSON, CSV for automation and scripting
• Clean separation: Visual indicators only in human-readable formats

💰 Live Price Fallback

• Automatic enrichment for newer instance types missing from the static pricing feed
• EC2 DescribeSpotPriceHistory API fetches current prices when static data shows $0
• Price source indicators show whether prices come from static data or live API
• Graceful degradation — works without AWS credentials, just shows $0 for missing types

🌐 Network Resilience

• Embedded data for offline functionality
• Graceful fallbacks when AWS APIs are unavailable
• Real-time API integration with intelligent caching

Quick Start

Installation

# macOS with Homebrew
brew tap alexei-led/tap
brew install alexei-led/tap/spotinfo

# Linux/Windows: Download from releases
curl -L https://github.com/alexei-led/spotinfo/releases/latest/download/spotinfo_linux_amd64.tar.gz | tar xz

# Docker
docker pull ghcr.io/alexei-led/spotinfo:latest

Supported platforms: macOS, Linux, Windows on AMD64/ARM64

Basic Usage

# Get placement scores for instances
spotinfo --type "m5.large" --with-score

# Find high-reliability instances with budget constraints
spotinfo --cpu 4 --memory 16 --with-score --min-score 8 --price 0.30

# Compare across regions with AZ-level details
spotinfo --type "t3.*" --with-score --az --region "us-east-1" --region "eu-west-1"

# Export data for automation
spotinfo --type "c5.*" --with-score --min-score 7 --output json

New Placement Score Flags

Flag	Description
--with-score	Enable real-time placement score fetching
--az	Get AZ-level scores instead of regional
--min-score N	Filter instances with score ≥ N (1-10)
--sort score	Sort by placement score

📖 Complete reference: Usage Guide | Examples

MCP Integration

spotinfo functions as a Model Context Protocol (MCP) server, enabling AI assistants to directly query AWS Spot Instance data through natural language.

Quick Setup with Claude Desktop

{
  "mcpServers": {
    "spotinfo": {
      "command": "spotinfo",
      "args": ["--mcp"]
    }
  }
}

Ask Claude: "Find cheapest t3 instances with placement score >7" or "Compare m5.large prices across US regions"

🤖 Full setup guide: MCP Server Documentation

Understanding AWS Spot Placement Scores

🚨 Key Insight: Placement scores are contextual - they evaluate success probability for your entire request, not individual instance types.

# Lower score (limited flexibility)
spotinfo --type "t3.micro" --with-score
# Score: 🔴 3

# Higher score (flexible options)
spotinfo --type "t3.*" --with-score  
# Score: 🟢 9

This is expected AWS behavior - providing multiple instance types gives AWS more fulfillment options.

📚 Learn more: AWS Spot Placement Scores

Documentation

Document	Description
Usage Guide	Complete CLI reference with all flags and examples
AWS Spot Placement Scores	Deep dive into placement scores with visual guides
Examples & Use Cases	Real-world DevOps scenarios and automation patterns
MCP Server Setup	Model Context Protocol integration guide
Data Sources	AWS data feeds, caching strategy, and troubleshooting

AWS Credentials

AWS credentials are optional but recommended for complete functionality:

Feature	Without Credentials	With Credentials
Spot advisor data	Full access	Full access
Static pricing	Full access	Full access
Live price fallback	Unavailable (shows $0 for missing types)	Fetches current prices via EC2 API
Placement scores	Unavailable	Real-time scores (1-10)

Required IAM permissions for full functionality:

• ec2:DescribeSpotPriceHistory — live price fallback for newer instance types
• ec2:GetSpotPlacementScores — placement score analysis

Credentials are loaded via the AWS SDK default credential chain (environment variables, shared config, IAM roles, etc.).

Development

Requirements: Go 1.24+, make, golangci-lint

# Build and test
make all

# Update embedded data
make update-data update-price

# Docker build
docker buildx build --platform=linux/arm64,linux/amd64 -t spotinfo .

CI/CD: Automated testing, linting, releases, and multi-arch Docker builds via GitHub Actions

Contributing

Contributions welcome! Please read the development commands in CLAUDE.md and ensure all tests pass.

License

Apache 2.0 License - see LICENSE for details.