cost-blame

Local-first CLI to attribute AWS cost spikes to services, tags, and likely resources.

cost-blame helps CloudOps and FinOps teams answer the critical question: "Who or what caused our AWS spend to rise?"

Built with Go, it runs entirely locally using AWS Cost Explorer and Resource APIs—no backend required.

Features

Spike Detection: Identify cost increases across services, regions, accounts, or tags
Anomaly Detection: Statistical analysis with z-score for detecting unusual cost patterns
New Spender Identification: Find resources that just started incurring costs
Tag-based Attribution: Blame cost changes on teams, apps, or environments via tags
Resource Drilldown: Map cost spikes to specific EC2, RDS, S3, Lambda, CloudFront, ECS, EKS resources
Multi-Account Support: Query across AWS Organizations or filter specific accounts
Export Options: CSV export and Slack webhook integration for alerts
Flexible Output: Human-readable tables or JSON for automation
AWS SDK v2: Fast, modern AWS integration with proper pagination and rate limiting

Installation

Homebrew (Recommended)

# Add the tap
brew tap pfrederiksen/tap

# Install cost-blame
brew install cost-blame

# Upgrade to latest version
brew upgrade cost-blame

Download Pre-built Binaries

Download the latest release for your platform from the releases page:

macOS (Intel)

curl -L https://github.com/pfrederiksen/cost-blame/releases/latest/download/cost-blame_0.2.2_Darwin_x86_64.tar.gz | tar xz
sudo mv cost-blame /usr/local/bin/

macOS (Apple Silicon)

curl -L https://github.com/pfrederiksen/cost-blame/releases/latest/download/cost-blame_0.2.2_Darwin_arm64.tar.gz | tar xz
sudo mv cost-blame /usr/local/bin/

Linux (amd64)

curl -L https://github.com/pfrederiksen/cost-blame/releases/latest/download/cost-blame_0.2.2_Linux_x86_64.tar.gz | tar xz
sudo mv cost-blame /usr/local/bin/

Linux (arm64)

curl -L https://github.com/pfrederiksen/cost-blame/releases/latest/download/cost-blame_0.2.2_Linux_arm64.tar.gz | tar xz
sudo mv cost-blame /usr/local/bin/

Windows Download the .zip file from the releases page and extract it to your PATH.

Using Go

go install github.com/pfrederiksen/cost-blame@latest

From Source

git clone https://github.com/pfrederiksen/cost-blame.git
cd cost-blame
make build
# Binary will be in ./bin/cost-blame

Requirements

AWS credentials configured (via ~/.aws/credentials or environment variables)
AWS Cost Explorer API access (requires payer account for multi-account visibility)
For building from source: Go 1.22+

Quick Start

Find top cost increases in the last 7 days

cost-blame spike --last 7d --threshold 100 --group-by service

Attribute costs by team tag

cost-blame blame --last 30d --tag-key team

Drill down into EC2 cost spike

cost-blame drilldown AmazonEC2 --last 48h --region us-west-2 --tag-key team

Commands

`cost-blame spike`

Detect cost spikes by comparing two equal time periods.

New in v0.2.0: Multi-account support, CSV export, Slack webhooks

Flags:

--last: Time window (48h, 7d, 30d)
--granularity: DAILY or HOURLY (default: DAILY)
--threshold: Minimum USD delta to report (default: 0)
--group-by: service, linked_account, region, or usage_type (default: service)
--tag-key: Optional tag dimension to group by
--accounts: Filter to specific account IDs (comma-separated)
--all-accounts: Query all accounts in AWS Organization
--top: Number of results (default: 10)
--json: Output as JSON
--csv: Export results to CSV file
--slack-webhook: Send alerts to Slack webhook URL
--profile: AWS profile
--region: AWS region (default: us-east-1)

Example:

cost-blame spike --last 7d --threshold 200 --group-by service --top 5

`cost-blame new-spend`

Find resources that recently started spending.

Flags: Same as spike, plus:

--min-current: Minimum current spend to consider (default: 50)

Example:

cost-blame new-spend --last 30d --min-current 100 --group-by service

`cost-blame blame`

Attribute cost changes by tag values.

Flags:

--tag-key: Tag to group by (required)
--tag-values: Optional CSV filter for specific values
Other flags same as spike

Example:

cost-blame blame --last 30d --tag-key team --threshold 50

`cost-blame drilldown`

Map a service cost spike to likely resources.

Arguments:

SERVICE: AWS service name (e.g., AmazonEC2, AmazonRDS)

Flags:

--last: Time window
--region: Filter to specific region
--account: Filter to specific account ID
--tag-key: Filter by tag key
--json: Output as JSON

Example:

cost-blame drilldown AmazonEC2 --last 48h --region us-west-2

How It Works

Cost Explorer Queries: Fetches cost data for current and prior periods
Delta Calculation: Computes absolute and percentage changes
Resource Correlation: Uses Resource Groups Tagging API and service-specific APIs (EC2, RDS) to identify resources
Attribution: Maps costs to tags, teams, or specific resource ARNs

Permissions Required

Minimum IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "tag:GetResources",
        "ec2:DescribeInstances",
        "ec2:DescribeVolumes",
        "ec2:DescribeNatGateways",
        "ec2:DescribeAddresses",
        "ec2:DescribeSnapshots",
        "rds:DescribeDBInstances"
      ],
      "Resource": "*"
    }
  ]
}

Note: Cost Explorer requires payer account credentials for consolidated billing visibility across linked accounts.

Configuration

cost-blame respects standard AWS SDK configuration:

AWS_PROFILE / --profile
AWS_REGION / --region
~/.aws/credentials and ~/.aws/config

Edge Cases & Limitations

Incomplete Data: Costs for the current day are not final; tool warns when window includes today
Hourly Granularity: Cost Explorer has constraints on hourly data retention
Currency: Assumes USD but displays actual currency from API responses
Permissions: Continues with partial results if some APIs are inaccessible

Development

# Build
make build

# Run tests
make test

# Lint (requires golangci-lint)
make lint

# Run locally
go run main.go spike --last 7d --debug

CI/CD

This project uses GitHub Actions for automated testing and releases:

Automated Testing: Every PR and push runs the full test suite
Multi-platform Releases: Automated builds for Linux, macOS, and Windows (amd64 + arm64)
Semantic Versioning: Tag a version (e.g., v0.1.0) to trigger an automated release

Creating a Release

# Tag the version
git tag v0.1.0

# Push the tag to trigger release workflow
git push origin v0.1.0

The release workflow will automatically:

Run all tests
Build binaries for all platforms
Generate checksums
Create a GitHub release with installation instructions

Contributing

Contributions welcome! This is an open-source project under the Apache 2.0 license.

Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Make your changes
Run tests (make test)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feat/amazing-feature)
Open a Pull Request

All PRs automatically run tests via GitHub Actions.

License

Apache License 2.0 - see LICENSE

Roadmap

✅ Multi-account support via AWS Organizations (v0.2.0)
✅ S3, Lambda, CloudFront, ECS, EKS drilldown (v0.2.0)
✅ Anomaly detection with statistical analysis (v0.2.0)
✅ CSV export and Slack webhook integration (v0.2.0)
Interactive TUI mode with bubble tea
PagerDuty integration
Cost forecasting and trend analysis
Budget threshold alerts

Built with ❤️ for CloudOps teams tired of mystery AWS bills.

`cost-blame anomaly`

Detect cost anomalies using statistical analysis (z-score).

Arguments:

--group-by: service or linked_account (default: service)
--historical-days: Number of days for baseline (default: 30)
--threshold: Z-score threshold for anomaly detection (default: 2.0)
--min-data-points: Minimum data points required (default: 7)
--anomalies-only: Show only detected anomalies
--top: Number of results (default: 20)
--json: Output as JSON

Example:

cost-blame anomaly --historical-days 30 --threshold 2.5 --anomalies-only

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
cmd		cmd
internal		internal
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TEST_COVERAGE.md		TEST_COVERAGE.md
coverage_report.txt		coverage_report.txt
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

cost-blame

Features

Installation

Homebrew (Recommended)

Download Pre-built Binaries

Using Go

From Source

Requirements

Quick Start

Find top cost increases in the last 7 days

Attribute costs by team tag

Drill down into EC2 cost spike

Commands

`cost-blame spike`

`cost-blame new-spend`

`cost-blame blame`

`cost-blame drilldown`

How It Works

Permissions Required

Configuration

Edge Cases & Limitations

Development

CI/CD

Creating a Release

Contributing

License

Roadmap

`cost-blame anomaly`

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

cost-blame

Features

Installation

Homebrew (Recommended)

Download Pre-built Binaries

Using Go

From Source

Requirements

Quick Start

Find top cost increases in the last 7 days

Attribute costs by team tag

Drill down into EC2 cost spike

Commands

cost-blame spike

cost-blame new-spend

cost-blame blame

cost-blame drilldown

How It Works

Permissions Required

Configuration

Edge Cases & Limitations

Development

CI/CD

Creating a Release

Contributing

License

Roadmap

cost-blame anomaly

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`cost-blame spike`

`cost-blame new-spend`

`cost-blame blame`

`cost-blame drilldown`

`cost-blame anomaly`

Packages