💰 infra-cost

Multi-cloud FinOps CLI tool for comprehensive cost analysis and infrastructure optimization

Take control of your cloud costs across AWS, Google Cloud, Azure, Alibaba Cloud, and Oracle Cloud 🚀

Installation • Quick Start • Features • Documentation • Development • Contributing

📢 Migrating from v0.x? infra-cost v1.0 introduces a new subcommand-based CLI architecture for better organization and discoverability.

• Quick migration: Run infra-cost config migrate to automatically update your configuration
• Command changes: Old flags are now organized subcommands (e.g., --inventory → export inventory json)
• Full guide: See MIGRATION_GUIDE.md for complete migration instructions

All new features and improvements are built on this solid foundation!

🎯 Why infra-cost?

Save money. Optimize resources. Make informed decisions.

• 💸 Reduce cloud spend by up to 30% with actionable insights
• 🔍 Multi-cloud visibility - see costs across all your providers in one place
• ⚡ Real-time analysis - get instant cost breakdowns and trends
• 🤖 AI-powered recommendations for optimization opportunities
• 📊 Executive reports - beautiful PDF reports for stakeholders
• 🔔 Smart alerting - proactive cost anomaly detection
• 💬 Team collaboration - Slack integration for cost awareness

🚀 Features

🌐 Multi-Cloud Support

• AWS ✅ (Full support with Cost Explorer integration)
• Google Cloud ✅ (BigQuery billing export, multi-project support)
• Microsoft Azure 🚧 (Architecture ready, coming soon)
• Alibaba Cloud 🚧 (Architecture ready, coming soon)
• Oracle Cloud 🚧 (Architecture ready, coming soon)

📊 Comprehensive Analytics

• Cost Forecasting - AI-powered predictions for future spending
• Budget Monitoring - Track against budgets with smart alerts
• Resource Rightsizing - ML recommendations for optimal instance sizes
• Sustainability Analysis - Carbon footprint tracking and green recommendations
• Security Cost Analysis - Security posture vs. cost optimization
• Anomaly Detection - AI-powered cost spike identification

🎛️ Advanced Features

• Interactive Dashboards - Rich terminal UI with real-time data
• PDF Report Generation - Executive summaries and technical deep-dives
• Cross-Cloud Optimization - Find the best provider for each workload
• Automated Optimization - Execute cost-saving actions automatically
• Audit Logging - Comprehensive compliance tracking
• Enterprise Multi-tenancy - Team and organization management

🔧 Developer Experience

• Multiple output formats: Fancy tables, plain text, JSON, CSV, Excel
• Flexible authentication: Environment variables, IAM roles, profiles
• CI/CD Integration: GitHub Actions, Jenkins, GitLab CI
• API Server: REST endpoints for custom integrations
• Webhook Support: Real-time notifications and integrations

📖 CLI Commands Overview

infra-cost v1.0 uses a modern subcommand-based architecture for better organization and discoverability.

⚡ Quick Commands

infra-cost now - Instant Cost Check (NEW in v1.2.0)

See today's cloud spending in one second - perfect for morning cost checks!

# Quick daily cost check (zero config)
infra-cost now

# Output:
# 💰 Today's Cost: $45.23 (+$3.12 ↑ from yesterday)
# 📊 Top Services: EC2 $22.10 | RDS $15.30 | S3 $4.20
# 📈 Month-to-Date: $892.45 / $1,500 (59%)
#    [███████████████████░░░░░░░░░░] 59%
#
# Provider: AWS
# Run `infra-cost cost` for detailed breakdown

Features:

• 🚀 Zero configuration - auto-detects your default AWS profile
• 📊 Smart summary - today's cost + delta from yesterday
• 🎯 Top 3 services - see where your money is going at a glance
• 💹 Budget progress - visual progress bar if budgets configured
• 🎨 Color-coded - green = under budget, red = over budget
• ⚡ Lightning fast - get your answer in ~1 second

Options:

infra-cost now                      # Default profile
infra-cost now --profile prod       # Specific profile
infra-cost now --provider gcp       # Google Cloud
infra-cost now --json               # JSON output for scripting

Perfect for:

• Morning stand-ups: "How much did we spend yesterday?"
• Quick sanity checks before demos
• Solo developers and indie hackers
• Anyone who wants instant cost visibility

infra-cost free-tier - AWS Free Tier Tracker (NEW in v1.2.0)

Track your AWS Free Tier usage and prevent surprise bills - perfect for solo developers and indie hackers!

# Check free tier status
infra-cost free-tier

# Output:
# 🆓 AWS Free Tier Status (Account: 123456789012)
# ════════════════════════════════════════════════════════════
#
# EC2 (t2.micro/t3.micro instances)
# ├── Used: 620.0 hours / 750 hours (82.7%)
# ├── [████████████████████████░░░░░░] 83%
# └── ⚠️ Warning: 130.0 hours remaining
#
# S3 (Standard storage)
# ├── Used: 4.2 GB / 5 GB (84.0%)
# ├── [████████████████████████░░░░░░] 84%
# └── ⚠️ Warning: 0.8 GB remaining
#
# Lambda (1M requests, 400K GB-sec)
# ├── Used: 0.0 cost / 0 cost (0.0%)
# ├── [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
# └── ✅ On track
#
# ────────────────────────────────────────────────────────────
# 💡 Tip: You have 8 days until month end

Features:

• 🆓 Tracks popular free tier services: EC2, S3, Lambda, RDS
• 📊 Visual progress bars - see usage at a glance
• ⚡ Smart alerts - warns when approaching limits (default: 80%)
• 💰 Cost projection - estimate month-end overages
• 🎯 Perfect for beginners - avoid surprise AWS bills
• 🚨 Status indicators - green=safe, yellow=warning, red=critical

Options:

infra-cost free-tier                       # Check current status
infra-cost free-tier --alert-threshold 90  # Custom threshold
infra-cost free-tier --show-projection     # Show projected overages
infra-cost free-tier --json                # JSON output

Tracked Services:

• EC2: 750 hours/month (t2.micro/t3.micro)
• S3: 5 GB storage
• Lambda: Cost-based tracking (free tier = $0 cost)

Perfect for:

• Solo developers and indie hackers
• Students learning AWS
• New AWS users avoiding surprise bills
• Monthly free tier checkups

infra-cost annotate - Cost Annotations for IaC Files (NEW in v1.3.0)

Add cost estimates directly in your Infrastructure as Code files - see costs during code review!

# Annotate Terraform files
infra-cost annotate --path ./terraform/

# Before:
resource "aws_instance" "web" {
  instance_type = "t3.xlarge"
  ami           = "ami-12345678"
}

# After:
# 💰 infra-cost: $121.47/month | aws_instance @ us-east-1
# 💡 Consider t3.large for 50% savings if CPU < 40% (saves $60.74/month)
# 📊 Last updated: 2026-01-30
resource "aws_instance" "web" {
  instance_type = "t3.xlarge"
  ami           = "ami-12345678"
}

Features:

• 📝 Terraform & CloudFormation support - HCL and YAML annotations
• 💰 Monthly cost estimates - see the cost of each resource
• 💡 Optimization suggestions - inline recommendations for savings
• 📊 Auto-update - keep annotations fresh with --update flag
• 🧹 Clean removal - remove all annotations with --remove
• 🔍 Dry run - preview changes before applying

Commands:

# Annotate all Terraform files in a directory
infra-cost annotate --path ./terraform/

# CloudFormation templates
infra-cost annotate --path ./cloudformation/ --format cloudformation

# Preview without modifying files
infra-cost annotate --path ./terraform/ --dry-run

# Update existing annotations
infra-cost annotate --path ./terraform/ --update

# Remove all cost annotations
infra-cost annotate --path ./terraform/ --remove

Perfect for:

• Code reviews with cost visibility
• DevOps engineers writing IaC
• Cost-aware development culture
• Pre-commit cost checks
• Documentation of infrastructure costs

infra-cost history - Git Cost History (NEW in v1.3.0)

Correlate cost changes with git commits - see which code changes impact costs!

# Show cost history with git correlation
infra-cost history --git

# Output:
# 📊 Cost History with Git Correlation
# ═══════════════════════════════════════════════════════════
# Date          Cost        Change      Commit
# ─────────────────────────────────────────────────────────
# 2026-01-28    $142.30     +$12.40     abc1234 Add GPU instances
# 2026-01-27    $129.90     +$45.20     def5678 Deploy new RDS
# 2026-01-26    $84.70      -$8.30      ghi9012 Cleanup unused EBS
# 2026-01-25    $93.00      +$3.10      jkl3456 Update Lambda memory
# ═══════════════════════════════════════════════════════════
#
# 🔍 Significant cost changes:
# • +$45.20 on 2026-01-27: def5678 "Deploy new RDS for analytics"
# • +$12.40 on 2026-01-28: abc1234 "Add GPU instances for ML"

# Analyze specific commit
infra-cost history --commit abc1234

# Who caused the most cost changes this month?
infra-cost blame --period month

Features:

• 📊 Cost-commit correlation - see which commits changed costs
• 👤 Author attribution - track cost impact by developer
• 📈 Trend analysis - understand cost evolution over time
• 🔍 Commit details - deep dive into specific commits
• 📝 Multiple formats - text, JSON, markdown output
• ⚠️ Significant change alerts - highlight big cost impacts

Commands:

# Show cost history for the past week (default)
infra-cost history --git

# Show history for different periods
infra-cost history --period month
infra-cost history --period quarter

# Filter by author
infra-cost history --author [email protected]

# Analyze specific commit
infra-cost history --commit abc1234

# Blame analysis - who impacted costs most?
infra-cost blame --period month

# Export to JSON for analysis
infra-cost history --format json > cost-history.json

Perfect for:

• Engineering teams tracking cost accountability
• Understanding which features drive costs
• Cost-aware code reviews
• FinOps culture and awareness
• Retrospectives on cost trends

infra-cost terraform - Terraform Cost Preview (NEW in v1.4.0)

Estimate infrastructure costs BEFORE deploying - shift-left cost management!

# Generate terraform plan and estimate costs
terraform plan -out=tfplan
infra-cost terraform --plan tfplan

# Output:
# ╭─────────────────────────────────────────────────────────────╮
# │             Terraform Cost Estimate                         │
# ├─────────────────────────────────────────────────────────────┤
# │ Resources to CREATE:                                        │
# │ ───────────────────────────────────────────────────────────│
# │ + aws_instance.web_server (t3.xlarge)                       │
# │   └── Monthly: $121.47 | Hourly: $0.1664                   │
# │ + aws_db_instance.primary (db.r5.large, 100GB gp2)          │
# │   └── Monthly: $182.80 | Hourly: $0.25                     │
# ├─────────────────────────────────────────────────────────────┤
# │ Resources to MODIFY:                                        │
# │ ───────────────────────────────────────────────────────────│
# │ ~ aws_instance.api_server                                   │
# │   └── t3.medium → t3.large: +$30.37/month                  │
# ├─────────────────────────────────────────────────────────────┤
# │ Resources to DESTROY:                                       │
# │ ───────────────────────────────────────────────────────────│
# │ - aws_instance.old_server                                   │
# │   └── Savings: -$60.74/month                               │
# ├─────────────────────────────────────────────────────────────┤
# │ SUMMARY                                                     │
# │ ───────────────────────────────────────────────────────────│
# │ Current Monthly Cost:     $1,240.50                         │
# │ Estimated New Cost:       $1,520.83                         │
# │ Difference:               +$280.33/month (+22.6%)          │
# │                                                             │
# │ ⚠️  Cost increase exceeds 20% threshold!                    │
# ╰─────────────────────────────────────────────────────────────╯

Usage Examples:

# Basic cost estimate
terraform plan -out=tfplan
infra-cost terraform --plan tfplan

# With cost threshold (fail if > 20% change)
infra-cost terraform --plan tfplan --threshold 20

# JSON format for automation
infra-cost terraform --plan tfplan --output json

# From JSON plan
terraform show -json tfplan > tfplan.json
infra-cost terraform --plan tfplan.json

Supported Resources:

• ✅ EC2 instances (all types)
• ✅ RDS instances with storage
• ✅ EBS volumes (gp2, gp3, io1, io2, st1, sc1)
• ✅ Load Balancers (ALB, NLB, CLB)
• ✅ NAT Gateways
• ✅ ElastiCache clusters
• ✅ S3 buckets (estimated)
• ✅ Lambda functions (estimated)

Perfect for:

• CI/CD cost gates
• Preventing expensive deployments
• Cost-aware infrastructure changes
• Shift-left FinOps culture
• Pre-deployment cost reviews

Command Migration Table

| Command Usage | Old Command (v0.x) | New Command (v1.0) | |--------------|-------------------|-------------------| | Cost Analysis | | Default cost analysis | infra-cost | infra-cost cost analyze | | Show cost deltas | infra-cost --delta | infra-cost cost analyze --show-delta | | Cost trends | infra-cost --trends 30 | infra-cost cost trends --period 30d | | Compare clouds | infra-cost --compare-clouds aws,gcp | infra-cost cost compare --providers aws,gcp | | Forecast costs | infra-cost --forecast 30 | infra-cost cost forecast --days 30 | | Optimization | | Optimization recommendations | infra-cost --finops | infra-cost optimize recommendations | | Quick wins | infra-cost --quick-wins | infra-cost optimize quickwins | | Rightsizing | infra-cost --rightsize | infra-cost optimize rightsizing | | Cross-cloud optimization | infra-cost --optimization-report | infra-cost optimize cross-cloud | | Monitoring & Alerts | | Cost alerts | infra-cost --alerts | infra-cost monitor alerts | | Budget monitoring | infra-cost --budgets | infra-cost monitor budgets | | Real-time monitoring | infra-cost --monitor | infra-cost monitor watch | | Anomaly detection | infra-cost --anomaly-detect | infra-cost monitor anomaly | | Export & Reports | | Export inventory (JSON) | infra-cost --inventory | infra-cost export inventory json | | Export inventory (CSV) | infra-cost --inventory-export csv | infra-cost export inventory csv | | Export inventory (Excel) | infra-cost --inventory-export xlsx | infra-cost export inventory xlsx | | Export inventory (PDF) | infra-cost --inventory-export pdf | infra-cost export inventory pdf | | AWS Organizations | | List accounts | infra-cost --organizations | infra-cost organizations list | | Organization summary | infra-cost --organizations-summary | infra-cost organizations summary | | Daily costs | infra-cost --organizations-daily | infra-cost organizations daily | | Chargeback | | Chargeback report | infra-cost --chargeback | infra-cost chargeback report | | Send to Slack | infra-cost --chargeback-slack | infra-cost chargeback slack | | Dashboards | | Interactive dashboard | infra-cost --dashboard | infra-cost dashboard interactive | | Multi-cloud dashboard | infra-cost --dashboard-multicloud | infra-cost dashboard multicloud | | Configuration | | Show configuration | infra-cost --config-status | infra-cost config show | | Generate configuration | infra-cost --config-generate | infra-cost config init | | Validate configuration | infra-cost --config-validate | infra-cost config validate | | Migrate configuration | N/A (new in v1.0) | infra-cost config migrate |

Available Command Groups

• cost - Cost analysis, trends, comparisons, and forecasting
• optimize - Optimization recommendations and analysis
• monitor - Alerts, budgets, and anomaly detection
• export - Export data in multiple formats
• organizations - AWS Organizations multi-account support
• chargeback - Cost allocation and reporting
• config - Configuration management
• dashboard - Interactive dashboards

Get help for any command:

infra-cost --help
infra-cost cost --help
infra-cost cost analyze --help

📦 Installation

npm (Recommended)

npm install -g infra-cost

Homebrew (macOS/Linux)

brew tap codecollab-co/tap
brew install infra-cost

npx (No installation required)

npx infra-cost

Docker

docker run --rm codecollab-co/infra-cost --help

GitHub Action

- uses: codecollab-co/[email protected]
  with:
    provider: aws
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

🎯 Quick Start

1. Basic AWS Cost Analysis

# Analyze costs with default AWS credentials
infra-cost cost analyze

# Show cost trends over time
infra-cost cost trends --period 30d

# Compare costs across multiple providers
infra-cost cost compare --providers aws,gcp

2. Google Cloud Platform Cost Analysis

# Analyze GCP costs with service account
infra-cost cost analyze \
  --provider gcp \
  --project-id my-project \
  --key-file /path/to/service-account.json

# List all accessible GCP projects
infra-cost cost analyze \
  --provider gcp \
  --project-id my-project \
  --list-projects

# Analyze costs with custom billing dataset
infra-cost cost analyze \
  --provider gcp \
  --project-id my-project \
  --billing-dataset custom_billing \
  --billing-table custom_table

# Compare costs across multiple GCP projects
infra-cost cost compare \
  --provider gcp \
  --projects project-1,project-2,project-3

3. Optimization & Recommendations

# Get AI-powered optimization recommendations
infra-cost optimize recommendations

# Find quick wins for immediate savings
infra-cost optimize quickwins

# Get rightsizing recommendations
infra-cost optimize rightsizing

4. Monitoring & Alerts

# Check cost alerts and budget status
infra-cost monitor alerts

# Monitor budgets
infra-cost monitor budgets

# Detect cost anomalies
infra-cost monitor anomaly

5. Team Collaboration

# Send cost report to Slack
infra-cost chargeback slack

# Generate chargeback report
infra-cost chargeback report

# Interactive dashboard
infra-cost dashboard interactive

🔐 Authentication

AWS Authentication (Multiple Methods)

1. Environment Variables (Recommended)

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
infra-cost cost analyze

2. AWS Profiles

# Use default profile
infra-cost cost analyze

# Use specific profile
infra-cost cost analyze --profile production

# Discover available profiles
infra-cost config show --discover-profiles

3. IAM Roles (EC2/Lambda/ECS)

# Automatically uses attached IAM role
infra-cost cost analyze

4. AWS SSO

aws sso login --profile my-sso-profile
infra-cost cost analyze --profile my-sso-profile

5. Configuration File

# Initialize configuration
infra-cost config init

# Validate configuration
infra-cost config validate

# Show current configuration
infra-cost config show

Google Cloud Platform Authentication

1. Service Account Key File (Recommended)

# Download service account key from GCP Console
# IAM & Admin > Service Accounts > Create Key (JSON)

export GOOGLE_PROJECT_ID=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
infra-cost cost analyze --provider gcp

2. Application Default Credentials (ADC)

# Authenticate with gcloud CLI
gcloud auth application-default login

# Set default project
gcloud config set project your-project-id

# Run infra-cost
infra-cost cost analyze --provider gcp --project-id your-project-id

3. Command-Line Arguments

infra-cost cost analyze \
  --provider gcp \
  --project-id my-project \
  --key-file /path/to/service-account.json

4. Configuration File

# Initialize configuration with GCP
infra-cost config init

# Edit ~/.infra-cost/config.json
{
  "provider": "gcp",
  "credentials": {
    "projectId": "my-project",
    "keyFilePath": "/path/to/service-account.json",
    "billingDatasetId": "billing_export",
    "billingTableId": "gcp_billing_export"
  }
}

GCP Permissions Required

Your service account needs the following IAM permissions:

• resourcemanager.projects.get - Read project information
• bigquery.jobs.create - Query billing data
• bigquery.tables.getData - Read billing tables

Recommended IAM Role: roles/bigquery.user + custom role for project access

Enable BigQuery Billing Export

infra-cost requires BigQuery billing export to be enabled:

1. Go to GCP Billing Console
2. Select your billing account
3. Navigate to "Billing export"
4. Enable "BigQuery export"
5. Configure dataset (default: billing_export)
6. Wait 24 hours for initial data

Multi-Cloud Setup

# Google Cloud Platform
infra-cost cost analyze --provider gcp --project-id my-project --key-file service-account.json

# Microsoft Azure (Coming Soon)
infra-cost cost analyze --provider azure --subscription-id sub-id --tenant-id tenant-id

# Oracle Cloud (Coming Soon)
infra-cost cost analyze --provider oracle --user-id user-ocid --tenancy-id tenancy-ocid

# Cross-cloud comparison
infra-cost cost compare --providers aws,gcp

# Cross-cloud optimization report (Coming Soon)
infra-cost optimize cross-cloud

📊 Output Examples

Default Rich Terminal UI

infra-cost cost analyze --output fancy

Export Options

# Export inventory to JSON
infra-cost export inventory json

# Export to CSV
infra-cost export inventory csv

# Export to Excel
infra-cost export inventory xlsx

# Export to PDF
infra-cost export inventory pdf

JSON for Automation

infra-cost cost analyze --output json

Interactive TUI Dashboard

Real-time cost monitoring with keyboard navigation

# Launch interactive TUI dashboard (shortcut)
infra-cost dashboard

# Or explicitly
infra-cost dashboard interactive

# Custom refresh interval (default: 60 seconds)
infra-cost dashboard --refresh 30

# Multi-cloud dashboard
infra-cost dashboard multicloud

Features:

• 🎨 Beautiful terminal UI with real-time updates
• ⌨️ Full keyboard navigation (vim-style supported)
• 📊 Multiple views: Services, Resources, Trends, Alerts
• 📈 Live trend indicators (↗ up, ↘ down, → stable)
• 🔔 Real-time alert notifications
• 🔄 Auto-refresh with configurable intervals
• 🎯 Drill-down into services and resources

Keyboard Shortcuts:

q       - Quit
r       - Refresh data
↑↓/jk   - Navigate rows
←→/hl   - Switch tabs
1-4     - Quick tab switch
?       - Help

Perfect for:

• DevOps engineers monitoring costs in terminal
• SREs with terminal-based workflows
• Real-time cost exploration
• Server environments without GUI

💬 Slack Integration

Enhanced Team Collaboration

• Rich cost breakdowns with visual charts
• Proactive alerts for budget overruns and anomalies
• Automated workflows for approval processes
• Team cost awareness with regular updates

Setup & Usage

# Configure Slack credentials (one-time setup)
export SLACK_TOKEN=xoxb-your-token
export SLACK_CHANNEL="#finops"

# Send chargeback report to Slack
infra-cost chargeback slack

# Or provide inline
infra-cost chargeback slack --slack-token xoxb-your-token --slack-channel "#finops"

Automated Daily Reports

name: Daily FinOps Report
on:
  schedule:
    - cron: '0 9 * * 1-5'  # Weekdays 9 AM UTC
jobs:
  cost-report:
    runs-on: ubuntu-latest
    steps:
      - run: |
          npx infra-cost chargeback slack \
            --slack-token ${{ secrets.SLACK_TOKEN }} \
            --slack-channel ${{ secrets.SLACK_CHANNEL }}

🤖 GitHub Actions Integration (v1.4.0+)

infra-cost is available as a GitHub Action, making it easy to integrate cost analysis into your CI/CD workflows with cost gates and automated PR comments.

Quick Cost Check

name: Cost Analysis
on: [pull_request]

jobs:
  cost-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: codecollab-co/[email protected]
        with:
          provider: aws
          command: now
          comment-on-pr: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Cost Gate - Fail on Increase

name: Cost Gate
on: pull_request

jobs:
  cost-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: codecollab-co/[email protected]
        with:
          provider: aws
          command: now
          fail-on-increase: true  # Fail if ANY cost increase
          cost-threshold: 1000     # Fail if monthly cost exceeds $1000
          comment-on-pr: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Terraform Cost Preview (Shift-Left)

name: Terraform Cost Check
on: pull_request

jobs:
  terraform-cost:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Terraform Plan
        run: terraform plan -out=tfplan

      - name: Cost Estimate
        uses: codecollab-co/[email protected]
        with:
          command: terraform
          additional-args: '--plan tfplan --threshold 20'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Daily Cost Report to Slack

name: Daily Cost Report
on:
  schedule:
    - cron: '0 9 * * *'

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: codecollab-co/[email protected]
        with:
          provider: aws
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          analysis-type: finops
          slack-webhook: ${{ secrets.SLACK_WEBHOOK }}

Action Inputs

| Input | Description | Default | |-------|-------------|---------| | provider | Cloud provider (aws, gcp, azure, alicloud, oracle) | aws | | profile | Cloud provider profile | default | | region | Cloud provider region | us-east-1 | | aws-access-key-id | AWS Access Key ID | - | | aws-secret-access-key | AWS Secret Access Key | - | | analysis-type | Type of analysis (summary, detailed, delta, forecast, anomaly, finops, audit) | summary | | forecast-days | Days for forecast | 30 | | delta-threshold | Alert threshold for cost changes (%) | 10 | | output-format | Output format (text, json) | text | | slack-webhook | Slack webhook URL | - | | comment-on-pr | Post analysis as PR comment | false | | fail-on-threshold | Fail if costs exceed threshold | false |

Action Outputs

| Output | Description | |--------|-------------| | total-cost | Total cost for the analysis period | | cost-change | Cost change percentage | | forecast-cost | Forecasted cost | | anomalies-detected | Number of anomalies detected | | report-json | Full report in JSON format |

See example workflows for more use cases.

🔧 Advanced Usage

AWS Organizations Support

Multi-Account Management

# List all accounts in organization
infra-cost organizations list

# Get organization-wide cost summary
infra-cost organizations summary

Daily Cost Reports with Slack Integration

# Get daily costs for all accounts
infra-cost organizations daily

# Send daily report to Slack
infra-cost organizations daily --slack-webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# View 30-day history
infra-cost organizations daily --days 30

# Get scheduling instructions for automated daily reports
infra-cost organizations daily --schedule-daily --schedule-time 09:00

# Export to JSON for automation
infra-cost organizations daily --json

Features:

• 📊 Multi-account cost breakdown
• 📈 Day-over-day cost trends with visual indicators
• 🔥 Top 5 spender accounts
• 📊 Weekly averages and projections
• 💬 Slack webhook integration for team notifications
• ⏰ Scheduling instructions (cron, Lambda, GitHub Actions)

Perfect for:

• Large organizations with multiple AWS accounts
• FinOps teams managing cross-account costs
• Daily cost visibility and team accountability
• Automated cost reporting workflows

Cost Analysis & Forecasting

# Analyze costs with delta comparison
infra-cost cost analyze --show-delta --delta-threshold 10

# Get cost trends
infra-cost cost trends --period 90d

# Compare costs across providers
infra-cost cost compare --providers aws,gcp,azure

# Forecast future costs
infra-cost cost forecast --days 30

Optimization Commands

# Get all optimization recommendations
infra-cost optimize recommendations

# Find quick wins for immediate savings
infra-cost optimize quickwins

# Get rightsizing recommendations
infra-cost optimize rightsizing

# Cross-cloud optimization analysis
infra-cost optimize cross-cloud

Monitoring & Alerts

# Check cost alerts
infra-cost monitor alerts

# Monitor budgets
infra-cost monitor budgets

# Watch for cost changes in real-time
infra-cost monitor watch

# Detect anomalies
infra-cost monitor anomaly

Configuration Management

# Initialize new configuration
infra-cost config init

# Show current configuration
infra-cost config show

# Validate configuration
infra-cost config validate

# Migrate from old version
infra-cost config migrate

🏗️ Architecture & Extensibility

Clean Architecture Structure (v1.0)

src/
├── cli/                        # CLI layer
│   ├── commands/              # Subcommand structure
│   │   ├── cost/             # Cost analysis commands
│   │   ├── optimize/         # Optimization commands
│   │   ├── monitor/          # Monitoring commands
│   │   ├── export/           # Export commands
│   │   ├── organizations/    # AWS Organizations commands
│   │   ├── chargeback/       # Chargeback commands
│   │   ├── config/           # Configuration commands
│   │   └── dashboard/        # Dashboard commands
│   ├── middleware/           # Auth, validation, error handling
│   └── index.ts              # CLI entry point
├── core/                      # Core business logic
│   ├── config/               # Configuration system
│   │   ├── schema.ts         # Zod validation schemas
│   │   ├── loader.ts         # Config file loading
│   │   ├── discovery.ts      # Profile discovery
│   │   └── profiles.ts       # Profile management
│   ├── logging/              # Structured logging
│   ├── analytics/            # Cost analytics engines
│   ├── optimization/         # Optimization engines
│   └── monitoring/           # Monitoring systems
├── providers/                 # Cloud provider implementations
│   ├── factory.ts            # Provider factory
│   └── aws/                  # AWS implementation ✅
│       ├── provider.ts       # Main provider class
│       ├── cost.ts           # Cost Explorer integration
│       ├── account.ts        # Account/Organizations
│       └── config.ts         # AWS-specific config
├── exporters/                # Output formatters
│   └── formats/
│       ├── fancy.ts          # Rich terminal output
│       ├── json.ts           # JSON output
│       ├── text.ts           # Plain text
│       └── slack.ts          # Slack formatting
└── enterprise/               # Enterprise features
    ├── multi-tenant/         # Multi-tenancy support
    └── audit/                # Audit logging

Key Design Principles

• Subcommand Architecture - Domain-organized, discoverable commands
• Clean Separation - CLI, core logic, and providers are decoupled
• Type Safety - Comprehensive TypeScript with Zod validation
• Testability - Dependency injection and mocking support
• Extensibility - Plugin architecture for new providers
• Configuration First - Unified config system with profiles

🚀 Roadmap

✅ Completed (2024-2025)

Core Platform & Architecture:

• ✅ Enhanced terminal UI and visualization
• ✅ AI-powered anomaly detection
• ✅ Comprehensive PDF reporting
• ✅ Advanced Slack integration
• ✅ GitHub Actions integration
• ✅ npm and Homebrew distribution
• ✅ Phase 1: Clean Architecture Restructuring (v1.0)
  • Subcommand-based CLI architecture
  • Unified configuration system with profiles
  • Automatic cloud profile discovery
  • Structured logging with audit trails
  • AWS Organizations support (Issue #10 ✅)
  • Cost allocation and chargeback reporting (Issue #30 ✅)
  • Configuration file support (Issue #29 ✅)
  • Caching layer for performance (Issue #28 ✅)
  • IAM Roles and environment variables auth (Issues #12, #13 ✅)
  • AWS SSO login support (Issue #9 ✅)

Multi-Cloud Foundation:

• ✅ Multi-cloud provider architecture (Issue #20 - foundation)
  • AWS provider fully implemented
  • GCP, Azure, Alibaba Cloud, Oracle Cloud - architecture ready

Q1 2026 (Current - In Progress)

Priority: Multi-Cloud Expansion

• ✅ Google Cloud Platform support - COMPLETE (Issue #66)
  • ✅ Provider implementation with BigQuery billing export
  • ✅ GCP authentication (service account, ADC)
  • ✅ Multi-project support with parallel retrieval
  • ✅ Multi-currency cost aggregation
  • ✅ Cost breakdown by service and time period
  • ✅ Resource inventory (GCE, Storage, SQL, GKE)
  • ✅ Budget tracking and alerts
  • ✅ Organization-level cost aggregation
  • ✅ Comprehensive documentation and examples
  • ✅ 65 unit tests passing (100% coverage)
• 📋 Advanced forecasting models (No GitHub issue)
  • ML-based cost predictions
  • Seasonal trend analysis
  • Budget recommendations
• 📋 Enhanced analytics (No GitHub issue)
  • Advanced cost attribution
  • Custom tagging strategies
  • Cost optimization scoring

Q2 2026 (Planned)

Priority: Complete Multi-Cloud & Automation

• 🔮 Microsoft Azure integration (Issue #20 - partial)
  • Azure Cost Management API
  • Subscription and resource group support
  • Azure-specific recommendations
• 🔮 Alibaba Cloud support (Issue #20 - partial)
  • Alibaba Cloud Cost API integration
  • Multi-region support
• 🔮 Oracle Cloud support (Issue #20 - partial)
  • OCI Cost Management integration
  • Compartment-based analysis
• 📋 Advanced automation engine (No GitHub issue)
  • Automated cost optimization actions
  • Policy-based automation
  • Approval workflows
  • Related: Issue #42 (Scheduled Reports), Issue #49 (API Server)

Q2 2026 (v1.3.0 - Phase 2 Complete)

Priority: Developer Experience & IDE Integration

• ✅ Interactive TUI Dashboard (Issue #43)
  • React Ink-based terminal UI
  • Real-time cost monitoring with keyboard navigation
  • Multiple views: Services, Resources, Trends, Alerts
• ✅ Cost Annotations for IaC Files (Issue #54)
  • Terraform and CloudFormation cost comments
  • Inline optimization suggestions
  • Update/remove annotations
• ✅ Git Cost History (Issue #56)
  • Cost-commit correlation
  • Blame analysis by author
  • Historical trend analysis
• 🔮 VS Code Extension (Issue #55 - Planned)
  • Inline cost display for Terraform/CloudFormation
  • Sidebar panel with cost summaries
  • CodeLens integration
  • Hover information with alternatives
  • Note: VS Code extension will be a separate repository
  • Integration points with CLI for cost data

Q2 2026 (v1.4.0 - Phase 3: CI/CD & Shift-Left)

Priority: CI/CD Integration & Shift-Left Cost Management

• ✅ GitHub Actions Integration (Issue #46)
  • Native GitHub Action for cost analysis in PRs
  • Cost gates with fail-on-increase and threshold checks
  • Enhanced PR comments with cost breakdown
  • Multiple output variables for downstream jobs
  • Slack notification support
• ✅ Terraform Cost Preview (Issue #47)
  • Parse terraform plan files (binary and JSON)
  • Estimate costs before deployment
  • Show create/modify/destroy breakdown
  • Cost threshold gates for CI/CD
  • Support for EC2, RDS, EBS, Load Balancers, and more
  • Monthly and hourly cost estimates
  • Shift-left cost management

Q2 2026 (v1.5.0 - Phase 4: Communication & Collaboration)

Priority: Communication & Collaboration

• ✅ Scheduled Reports with Daemon Mode (Issue #42)
  • Built-in scheduler daemon for automated reports
  • Cron-based scheduling with timezone support
  • Multiple schedules per instance
  • Systemd service file generation
  • Execution logs and status monitoring
• ✅ Microsoft Teams Integration (Issue #45)
  • Incoming webhook support with Adaptive Cards
  • Multiple card styles (compact, detailed, executive)
  • Cost summaries and alert integration
  • Chargeback reports for Teams
• ✅ PagerDuty & OpsGenie Integration (Issue #48)
  • PagerDuty Events API v2 support
  • OpsGenie Alert API integration
  • Severity/priority mapping
  • Auto-resolve functionality
  • Deduplication to prevent spam
• ✅ Email Report Scheduling (Issue #58)
  • SendGrid and Mailgun support
  • Beautiful HTML email templates
  • Multiple recipient support
  • Scheduler integration for automated emails
  • Plain text fallback

Q3 2026 (Planned)

Priority: Enterprise Features

• ✅/🚧 Enterprise SSO integration
  • AWS SSO: ✅ Completed (Issue #9)
  • SAML/OAuth support: 🔲 Planned (Issue #52)
  • Azure AD, Okta, Auth0 integration: 🔲 Planned
  • Role-based access control (RBAC): 🔲 Planned (Issue #50)
• 📋 Custom plugin system (No GitHub issue)
  • Plugin SDK
  • Custom provider support
  • Third-party integrations
• 📋 Mobile app companion (No GitHub issue)
  • iOS and Android apps
  • Real-time cost alerts
  • Executive dashboards on mobile

Future Vision

FinOps & Intelligence:

• 📋 Sustainability tracking expansion (No GitHub issue)
  • Carbon footprint tracking
  • Green cloud recommendations
  • Renewable energy usage analytics
• 🔲 FinOps best practices automation (Issue #59 - partial)
  • FinOps Scorecards implementation
  • Automated best practices enforcement
  • Team performance metrics
• 🔲 AI-powered cost conversations (Issue #44 - partial)
  • Natural language cost queries
  • ChatOps integration
  • AI cost assistant

Platform & Scale:

• 📋 Multi-tenant SaaS platform (No GitHub issue)
  • Organization management
  • Team collaboration features
  • Centralized cost governance
• 🔲 Additional integrations (Various open issues)
  • Microsoft Teams (Issue #45)
  • PagerDuty/OpsGenie (Issue #48)
  • Terraform cost preview (Issue #47)
  • API Server mode (Issue #49)
  • Multi-cloud dashboard (Issue #62)
  • Web-based dashboards (Issue #60)

Legend:

• ✅ Completed
• 🚧 In Progress
• 🔮 Planned (this quarter)
• 🔲 Open GitHub Issue
• 📋 Not yet tracked in GitHub issues

📋 Requirements & Permissions

AWS Permissions Required

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InfraCostMinimalPermissions",
      "Effect": "Allow",
      "Action": [
        "iam:ListAccountAliases",
        "ce:GetCostAndUsage",
        "ce:GetRightsizingRecommendation",
        "ce:GetSavingsUtilization",
        "budgets:ViewBudget",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

System Requirements

• Node.js 20+ (required)
• Memory: 512MB+ available
• Network: Internet access for cloud provider APIs
• Optional: Docker for containerized deployments

🧪 Development

📚 Developer Resources: See the docs/ folder for comprehensive technical documentation including architecture guides, testing reports, and release procedures.

Local Development Setup

# Clone repository
git clone https://github.com/codecollab-co/infra-cost.git
cd infra-cost

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev

Testing & Quality Assurance

# Type checking
npm run typecheck

# Linting
npm run lint

# Security audit
npm audit

# Test coverage
npm run test:coverage

Release Management

# Check current version status
npm run version:check

# Bump version
npm run version:bump:patch   # Bug fixes
npm run version:bump:minor   # New features
npm run version:bump:major   # Breaking changes

# Prepare release
npm run prepare-release

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

🌟 Ways to Contribute

• ⭐ Star this repository to show your support
• 🐛 Report bugs and suggest improvements via issues
• 📝 Improve documentation - help others understand and use the tool
• 🔧 Add cloud provider support - help us expand to more providers
• 🧪 Write tests - improve code quality and reliability
• 💡 Suggest features - share your ideas for new capabilities

🚀 Getting Started with Contributing

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/infra-cost.git
3. Create a branch: git checkout -b feature/amazing-feature
4. Make changes and write tests
5. Run quality checks: npm run typecheck && npm run lint && npm test
6. Commit: git commit -m "Add amazing feature"
7. Push: git push origin feature/amazing-feature
8. Create a Pull Request

📋 Contribution Guidelines

• Follow the existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Keep PRs focused on a single feature/fix
• Be respectful and constructive in discussions

🏷️ Good First Issues

Look for issues labeled good first issue or help wanted to get started!

📞 Support & Community

💬 Get Help

• 📚 Documentation: docs.codecollab.co/infra-cost (coming soon)
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Email Support: [email protected]

🌟 Show Your Support

If infra-cost helps you save money and optimize costs, please:

• ⭐ Star this repository
• 🐦 Share on Twitter with #InfraCost #FinOps
• 📝 Write a review or blog post about your experience
• 🤝 Contribute code, documentation, or feedback

🏢 Enterprise Support

For enterprise deployments, custom integrations, and professional support:

• 📧 Contact: [email protected]
• 🔒 SLA-backed support available
• 🎨 Custom branding and whitelabeling
• 🏗️ Professional services and consulting

📚 Documentation

📖 User Documentation

• README.md - Main project documentation (you are here)
• CHANGELOG.md - Version history and release notes
• CONTRIBUTING.md - Contribution guidelines

🔧 Developer Documentation

Comprehensive technical documentation is available in the docs/ folder:

• docs/RELEASE_SUMMARY.md - Complete release guide for GitHub, npm, and Homebrew
• docs/PRODUCTION_READINESS.md - Production readiness assessment and checklist
• docs/TEST_RESULTS.md - Comprehensive test results and analysis
• docs/NPM_PUBLISHING.md - npm publishing workflow and best practices
• docs/HOMEBREW_SETUP.md - Homebrew formula creation guide
• docs/code_flow.md - Codebase architecture and flow
• docs/infra_cost_cli.md - CLI implementation details
• docs/MULTI-CLOUD-INVENTORY.md - Multi-cloud features
• docs/ENHANCED-FEATURES.md - Advanced capabilities

See docs/README.md for the complete documentation index.

📄 License

MIT © Code Collab

🔄 Changelog

v1.0.0 - Major Release (Phase 1: Clean Architecture) 🎉

• ✅ Subcommand-Based CLI - New organized command structure
  • cost - Cost analysis and trends
  • optimize - Optimization recommendations
  • monitor - Alerts and monitoring
  • export - Data export in multiple formats
  • organizations - AWS Organizations support
  • chargeback - Cost allocation and reporting
  • config - Configuration management
  • dashboard - Interactive dashboards
• ✅ Unified Configuration System - Single config file with profiles
• ✅ Profile Discovery - Auto-detect cloud provider profiles
• ✅ Clean Architecture - Separation of CLI, core, and providers
• ✅ Enhanced Logging - Structured logging with multiple outputs
• ✅ Migration Tool - Automated migration from v0.x (infra-cost config migrate)
• ✅ Improved Error Handling - Better error messages and validation
• ✅ TypeScript Improvements - Full type safety with Zod schemas

Breaking Changes: See MIGRATION_GUIDE.md for upgrading from v0.x

v0.3.0

• ✅ GitHub Marketplace Action - Integrate cost analysis into CI/CD workflows
• ✅ Node.js 20+ support - Updated runtime requirements
• ✅ Sprint 6 UX improvements - Enhanced user experience
• ✅ Configuration improvements - Better config resolution and file permissions
• ✅ Date normalization - Consistent UTC date handling

v0.2.4

• ✅ Fixed CommonJS compatibility - Homebrew installation now works perfectly
• ✅ Enhanced error handling and user experience improvements
• ✅ Optimized build process for better performance

v0.2.0 - Enhanced Features

• ✅ AI-powered anomaly detection with real-time monitoring
• ✅ Advanced visualization engine with interactive dashboards
• ✅ PDF report generation for executives and technical teams
• ✅ Comprehensive Slack integration with rich formatting
• ✅ Multi-cloud architecture ready for expansion
• ✅ Enterprise features including multi-tenancy and API server

Migration from v0.x

See the comprehensive MIGRATION_GUIDE.md for step-by-step instructions on migrating from v0.x to v1.0.

Made with ❤️ by Code Collab

Empowering teams to optimize cloud costs and build sustainable infrastructure

⭐ Star us on GitHub • 🐦 Follow on Twitter • 💼 LinkedIn