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 allsupport - 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 typesec2: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.