instancepedia 0.2.3

EC2 Instance Type Browser - TUI and CLI

Instancepedia - EC2 Instance Type Browser

A Terminal User Interface (TUI) and Command-Line Interface (CLI) application for browsing AWS EC2 instance types with detailed information and free tier eligibility. Use the interactive TUI for exploration or the CLI for scripting and automation.

Features

TUI Mode (Interactive)

• 🗺️ Region Selection: Browse instance types for any AWS region you have access to
• 📋 Categorized Instance List: View all available EC2 instance types organized by family and category
  • Hierarchical tree structure: Categories → Families → Instances
  • Categories include: General Purpose, Compute Optimized, Memory Optimized, Burstable Performance, GPU Instances, Storage Optimized, etc.
  • Instances grouped by family (e.g., m5, m6i, t2, t3) within categories
  • Root node and families expand automatically when parent categories are expanded
  • Expand/collapse categories and families to reduce clutter
  • Expanded state is preserved during pricing updates
• 💰 Pricing Information: See on-demand and spot prices for each instance type
  • Prices load in the background for all instance types
  • Real-time pricing updates in the tree view (throttled to preserve expanded state)
  • Batch fetching for optimal performance
  • Automatic retry with exponential backoff on rate limits
  • Pricing displayed directly in the instance list: instance type, vCPU, memory, and price per hour
• 💵 Cost Calculator: Automatic calculation of monthly and annual costs, plus cost per vCPU and GB RAM
• 🔍 Search & Filter: Search by instance type name, filter by free tier eligibility
• 📊 Detailed Information: Comprehensive details for each instance type including:
  • Compute specifications (vCPU, cores, threads)
  • Memory information
  • Network performance
  • Storage options (EBS, instance store)
  • Architecture support
  • Pricing and cost analysis with spot price savings
• 🆓 Free Tier Indicators: Clearly marked free tier eligible instances
• ⚡ Fast Navigation: Smooth screen transitions with loading indicators
• 🐛 Debug Mode: Scrolling debug log for troubleshooting (use --debug flag)

CLI Mode (Headless)

• 🔧 Scriptable: Perfect for automation, CI/CD pipelines, and scripting
• 📊 Multiple Output Formats: Table (human-readable), JSON (machine-readable), CSV (spreadsheet-friendly)
• 🔍 Powerful Filtering: Search, filter by family, free tier only, and more
• 💰 Pricing Queries: Get pricing information for specific instances (on-demand and spot prices)
• 📈 Comparison: Compare two instance types side-by-side with detailed metrics
• 📁 File Output: Save results to files for further processing
• ⚡ Fast: No UI overhead, optimized for batch operations
• 🔇 Quiet Mode: Suppress progress messages for clean script output

Installation

From PyPI (Recommended)

pip install instancepedia

From Source

1. Clone the repository:

git clone https://github.com/pfrederiksen/instancepedia.git
cd instancepedia

2. Install dependencies:

pip install -r requirements.txt

Or install in development mode:

pip install -e .

Configure AWS Credentials

After installation, configure AWS credentials (one of the following):

• Run aws configure
• Set environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• Use an AWS profile: export AWS_PROFILE=your-profile

Usage

TUI Mode (Interactive)

After installation from PyPI, simply run:

instancepedia

Or explicitly launch TUI mode:

instancepedia --tui

Or with debug mode enabled (shows scrolling debug log):

instancepedia --tui --debug

If you installed from source (development mode), you can also run:

python3 -m src.main

Note: Pricing information loads in the background after instance types are displayed. You'll see:

• A progress indicator in the header showing how many prices have been loaded
• "⏳ Loading..." in the tree for instances that don't have pricing yet
• Real-time updates as prices load (tree updates are throttled to preserve your expanded sections)
• The application uses parallel requests and batch processing to fetch pricing efficiently, with automatic retry logic for rate-limited requests
• Your expanded categories and families remain open during pricing updates

CLI Mode (Headless)

The CLI mode provides command-line access to all functionality, perfect for scripting and automation.

List Instance Types

# List all instance types in a region
instancepedia list --region us-east-1

# List as JSON (for scripting)
instancepedia list --region us-east-1 --format json

# List as CSV (for spreadsheets)
instancepedia list --region us-east-1 --format csv --output instances.csv

# Filter by search term
instancepedia list --region us-east-1 --search t3

# Show only free tier instances
instancepedia list --region us-east-1 --free-tier-only

# Filter by instance family
instancepedia list --region us-east-1 --family m5

# Include pricing information (slower)
instancepedia list --region us-east-1 --include-pricing

Show Instance Details

# Show detailed information for a specific instance
instancepedia show t3.micro --region us-east-1

# Show with pricing
instancepedia show t3.micro --region us-east-1 --include-pricing

# Output to file
instancepedia show t3.micro --region us-east-1 --format json --output t3-micro.json

Search Instance Types

# Search for instances matching a term
instancepedia search m5 --region us-east-1

# Search with filters
instancepedia search t3 --region us-east-1 --free-tier-only

Get Pricing Information

# Get pricing for a specific instance
instancepedia pricing t3.micro --region us-east-1

# Get pricing as JSON
instancepedia pricing t3.micro --region us-east-1 --format json

Example Output (table format):

Pricing for t3.micro in us-east-1:

On-Demand: $0.0104/hr
Monthly (730 hrs): $7.59
Annual: $91.10
Spot: $0.0036/hr
Spot Savings: 65.4%

List Available Regions

# List all available regions
instancepedia regions

# List as JSON
instancepedia regions --format json

Compare Instance Types

# Compare two instance types
instancepedia compare t3.micro t3.small --region us-east-1

# Compare with pricing
instancepedia compare t3.micro t3.small --region us-east-1 --include-pricing

Example Output (table format):

+--------------------+-----------------+-----------------+
| Property           | t3.micro        | t3.small        |
+====================+=================+=================+
| Instance Type      | t3.micro        | t3.small        |
+--------------------+-----------------+-----------------+
| vCPU               | 2               | 2               |
+--------------------+-----------------+-----------------+
| Memory (GB)        | 1.0             | 2.0             |
+--------------------+-----------------+-----------------+
| Network            | Up to 5 Gigabit | Up to 5 Gigabit |
+--------------------+-----------------+-----------------+
| On-Demand Price/hr | $0.0104         | $0.0208         |
+--------------------+-----------------+-----------------+
| Free Tier Eligible | Yes 🆓           | No              |
+--------------------+-----------------+-----------------+

Common Options

All CLI commands support these common options:

• --region <region> - AWS region (default: from config or us-east-1)
• --profile <profile> - AWS profile name (overrides environment variable)
• --format <format> - Output format: table (default), json, or csv
• --output <file> - Write output to file instead of stdout
• --quiet - Suppress progress messages (useful for scripting)
• --debug - Enable debug output with tracebacks

Note:

• When using --format json, output is valid JSON that can be piped to jq or parsed by other tools
• CSV format is suitable for importing into spreadsheets
• CLI commands return exit code 0 on success, 1 on error (useful for scripting)
• Progress messages are sent to stderr, so output can be redirected cleanly: instancepedia list --region us-east-1 --format json > output.json

Examples

# Export all free tier instances to CSV
instancepedia list --region us-east-1 --free-tier-only --format csv --output free-tier.csv

# Get pricing for multiple instances (using shell loop)
for instance in t3.micro t3.small t3.medium; do
  instancepedia pricing $instance --region us-east-1 --format json
done

# Find all m5 instances with pricing
instancepedia list --region us-east-1 --family m5 --include-pricing --format json

# Compare instances across different regions
instancepedia compare t3.micro t3.small --region us-east-1 --include-pricing

# Search and filter with quiet mode (for scripts)
instancepedia search t3 --region us-east-1 --free-tier-only --format json --quiet

# Get instance details as JSON for processing
instancepedia show t3.micro --region us-east-1 --include-pricing --format json | jq '.instance.pricing'

Keyboard Shortcuts

Region Selector

• ↑ ↓ - Navigate regions
• Enter - Select region
• Esc / Q - Quit

Instance List

• ↑ ↓ - Navigate tree (move between categories, families, and instances)
• Enter - View details (on instance) or expand/collapse (on category/family)
• Space - Expand/collapse category or family
• / - Focus search input
• F - Toggle free tier filter (show only free tier eligible instances)
• Esc - Back to region selector
• Q - Quit

Tree Navigation Tips:

• The root "Instance Types" node is expanded by default
• Categories are collapsed by default to reduce initial clutter
• When you expand a category, all family nodes within it are automatically expanded
• Instance nodes show: instance type | vCPU count | memory | price | free tier indicator
• Search and filters work across all categories and families

Instance Detail

• Esc - Back to list
• Q - Quit

Configuration

You can configure the application using environment variables:

• INSTANCEPEDIA_AWS_REGION - Default AWS region (default: us-east-1)
• INSTANCEPEDIA_AWS_PROFILE - AWS profile to use

IAM Permissions

Instancepedia requires minimal AWS permissions to function. The application needs read-only access to EC2 instance type information and pricing data.

Required IAM Policy

Create an IAM policy with the following JSON:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeRegions",
                "ec2:DescribeInstanceTypes",
                "ec2:DescribeSpotPriceHistory"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "pricing:GetProducts"
            ],
            "Resource": "*"
        }
    ]
}

Note: The pricing:GetProducts permission is required to display on-demand pricing. The ec2:DescribeSpotPriceHistory permission is required to display current spot prices. If you don't need pricing information, you can omit these permissions and the application will still function (pricing will show as "N/A").

The application handles AWS API rate limiting automatically with exponential backoff retry logic, so you don't need to worry about rate limit errors.

Setting Up IAM Permissions

1. Create the policy (using AWS CLI):

   aws iam create-policy \
     --policy-name InstancepediaReadOnly \
     --policy-document file://instancepedia-policy.json
   

2. Attach the policy to a user:

   aws iam attach-user-policy \
     --user-name YOUR_USERNAME \
     --policy-arn arn:aws:iam::ACCOUNT_ID:policy/InstancepediaReadOnly
   

3. Or attach to a role (for EC2 instances, Lambda, etc.):

   aws iam attach-role-policy \
     --role-name YOUR_ROLE_NAME \
     --policy-arn arn:aws:iam::ACCOUNT_ID:policy/InstancepediaReadOnly
   

Note: Replace YOUR_USERNAME, YOUR_ROLE_NAME, and ACCOUNT_ID with your actual values.

Alternatively, you can use the AWS Console:

1. Go to IAM → Policies → Create policy
2. Select JSON tab and paste the policy above
3. Name it InstancepediaReadOnly and create it
4. Attach it to your user or role as needed

Performance

Instancepedia is optimized for performance in both TUI and CLI modes:

TUI Mode

• Parallel Pricing Fetching: Uses thread pools to fetch pricing data concurrently (5 parallel workers)
• Batch Spot Price Queries: Fetches spot prices in batches of up to 50 instance types per API call
• Automatic Retry: Handles rate limiting with exponential backoff (1s, 2s, 4s, etc.)
• Background Loading: Pricing loads in the background so you can browse instance types immediately
• Throttled UI Updates: Tree updates are throttled (every 10 pricing updates) to prevent UI flicker and preserve expanded state
• State Preservation: Expanded categories and families are preserved during tree rebuilds

CLI Mode

• Efficient Filtering: Filters are applied in-memory after fetching, minimizing API calls
• Optional Pricing: Pricing is only fetched when --include-pricing is specified
• Parallel Processing: When fetching pricing for multiple instances, uses parallel requests (5 workers)
• Streaming Output: Results are printed as they're processed (for table format)
• Fast JSON/CSV Export: Direct serialization without UI overhead

Requirements

• Python 3.8+
• AWS credentials configured
• Dependencies (installed automatically with pip):
  • boto3>=1.28.0 - AWS SDK
  • textual>=0.40.0 - TUI framework
  • pydantic>=2.0.0 - Data validation
  • pydantic-settings>=2.0.0 - Settings management
  • tabulate>=0.9.0 - Table formatting for CLI

Development

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/pfrederiksen/instancepedia.git
cd instancepedia

2. Install in development mode with dev dependencies:

pip install -e ".[dev]"

This installs the package in editable mode along with development tools (build, twine, pytest).

Creating Releases

Releases are automated using the release script. The script handles version bumping, git tagging, and triggering GitHub releases.

Prerequisites:

• Be on the main branch
• Have a clean working directory (no uncommitted changes)
• Be up to date with the remote repository

Usage:

# Bump patch version (0.1.1 -> 0.1.2)
./scripts/release.sh patch

# Bump minor version (0.1.1 -> 0.2.0)
./scripts/release.sh minor

# Bump major version (0.1.1 -> 1.0.0)
./scripts/release.sh major

# Use a specific version
./scripts/release.sh 0.2.0

The script will:

1. Update the version in pyproject.toml
2. Create a commit with the version bump
3. Create an annotated git tag (e.g., v0.1.2)
4. Push the commit to main
5. Push the tag (which automatically triggers the GitHub Actions workflow to create a GitHub release)

Note: After creating a release, you can publish to PyPI using the publish script (see below).

Building and Publishing

To build the package for PyPI:

1. Install build tools (use a virtual environment):

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade build twine

2. Build the package:

python3 -m build

3. Check the package:

python3 -m twine check dist/*

4. Publish to TestPyPI (recommended first):

python3 -m twine upload --repository testpypi dist/*

5. Publish to PyPI:

python3 -m twine upload dist/*

Or use the helper script:

./scripts/publish.sh testpypi  # Test first
./scripts/publish.sh pypi      # Production

Running Tests

The test suite includes comprehensive tests for all CLI functionality:

# Run all tests (48 tests covering CLI commands, output formatters, and parsers)
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_cli_output.py
pytest tests/test_cli_commands.py
pytest tests/test_cli_parser.py

# Run with verbose output
pytest -v

# Run tests without coverage (faster)
pytest --no-cov

Test Coverage:

• ✅ Output formatters (Table, JSON, CSV) - 24 tests
• ✅ CLI command handlers - 9 tests
• ✅ Argument parser - 15 tests
• ✅ All tests use mocking to avoid requiring AWS credentials

The test suite validates all CLI functionality including error handling, output formatting, and command parsing.

Project Structure

instancepedia/
├── src/                      # Source code
│   ├── __init__.py
│   ├── app.py                # Main TUI application
│   ├── main.py               # Entry point (supports both TUI and CLI)
│   ├── debug.py              # Debug utilities
│   ├── cli/                  # CLI module (headless mode)
│   │   ├── __init__.py
│   │   ├── commands.py       # CLI command handlers
│   │   ├── output.py         # Output formatters (table, JSON, CSV)
│   │   └── parser.py         # Argument parser
│   ├── config/               # Configuration
│   │   ├── __init__.py
│   │   └── settings.py       # Configuration settings
│   ├── models/               # Data models
│   │   ├── __init__.py
│   │   ├── free_tier.py
│   │   ├── instance_type.py
│   │   └── region.py
│   ├── services/             # AWS service wrappers
│   │   ├── __init__.py
│   │   ├── aws_client.py
│   │   ├── free_tier_service.py
│   │   ├── instance_service.py
│   │   └── pricing_service.py
│   └── ui/                   # TUI screens
│       ├── __init__.py
│       ├── instance_detail.py
│       ├── instance_list.py
│       └── region_selector.py
├── tests/                    # Test suite
│   ├── __init__.py
│   ├── conftest.py           # Pytest fixtures
│   ├── test_cli_commands.py  # CLI command tests
│   ├── test_cli_output.py    # Output formatter tests
│   └── test_cli_parser.py    # Argument parser tests
├── scripts/                  # Utility scripts
│   ├── publish.sh            # PyPI publishing helper
│   └── release.sh            # Release automation script
├── screenshots/              # Application screenshots
├── .gitignore               # Git ignore rules
├── LICENSE                  # MIT License
├── MANIFEST.in              # Package manifest for PyPI
├── pyproject.toml           # Project configuration and metadata
├── requirements.txt         # Python dependencies
└── README.md                # This file

License

MIT