ccExplorer

AWS Cost Explorer for the command line

Query, filter, and visualize your AWS costs without leaving the terminal

Quick Start

brew tap cduggn/cduggn && brew install ccexplorer

# See your costs by service (current month)
ccexplorer get aws -g DIMENSION=SERVICE

Tip

Use the -l flag to exclude credits and refunds for accurate cost analysis.

Features

• Multi-dimensional grouping - Group costs by service, operation, account, or tags
• Flexible filtering - Filter by any AWS dimension or cost allocation tag
• Multiple outputs - Table, CSV, charts, or vector database
• Date ranges - Daily, monthly, or hourly granularity
• AI-ready - Export to Pinecone for semantic search with LangChain
• MCP integration - Use with GitHub Copilot and VSCode

Installation

Homebrew (recommended)

brew tap cduggn/cduggn
brew install ccexplorer

Docker

docker pull ghcr.io/cduggn/ccexplorer:latest

docker run -it \
  -e AWS_ACCESS_KEY_ID=<your-key> \
  -e AWS_SECRET_ACCESS_KEY=<your-secret> \
  -e AWS_REGION=us-east-1 \
  ghcr.io/cduggn/ccexplorer:latest get aws -g DIMENSION=SERVICE

From source

git clone https://github.com/cduggn/ccExplorer.git
cd ccExplorer
make build
./bin/ccexplorer get aws -g DIMENSION=SERVICE

Usage

Basic Queries

# Costs by service
ccexplorer get aws -g DIMENSION=SERVICE

# Costs by service and operation
ccexplorer get aws -g DIMENSION=SERVICE,DIMENSION=OPERATION -l

# Costs by linked account
ccexplorer get aws -g DIMENSION=LINKED_ACCOUNT

Filtering

# Filter by service
ccexplorer get aws -g DIMENSION=OPERATION,DIMENSION=SERVICE -f SERVICE="Amazon DynamoDB" -l

# Filter by operation
ccexplorer get aws -g DIMENSION=OPERATION,DIMENSION=SERVICE -f OPERATION="GetCostAndUsage" -l

# Filter by cost allocation tag
ccexplorer get aws -g TAG=ApplicationName,DIMENSION=OPERATION -f TAG="my-project" -l

Date Ranges & Granularity

# Custom date range
ccexplorer get aws -g DIMENSION=SERVICE -s 2024-01-01 -e 2024-01-31

# Daily granularity
ccexplorer get aws -g DIMENSION=SERVICE,DIMENSION=OPERATION -m DAILY -s 2024-01-01 -e 2024-01-07

# Hourly granularity (requires ISO 8601 timestamps)
ccexplorer get aws -g DIMENSION=SERVICE -m HOURLY -s 2024-01-01T00:00:00Z -e 2024-01-02T00:00:00Z

Output Formats

# CSV export
ccexplorer get aws -g DIMENSION=SERVICE -p csv

# Chart (generates HTML file)
ccexplorer get aws -g DIMENSION=SERVICE,DIMENSION=OPERATION -p chart -l

# Pinecone vector database
ccexplorer get aws -g DIMENSION=SERVICE,DIMENSION=USAGE_TYPE -p pinecone -l

Configuration

AWS Authentication

ccExplorer uses the standard AWS credential chain. Set one of:

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: Access keys
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

Pinecone Integration

For vector database output, set these additional variables:

export OPENAI_API_KEY=your-openai-key
export PINECONE_API_KEY=your-pinecone-key
export PINECONE_INDEX=https://your-index.svc.us-east-1-aws.pinecone.io

Note

The -p pinecone flag does not support LINKED_ACCOUNT dimension to prevent sending sensitive data.

Advanced Features

MCP Server Integration

ccExplorer includes a built-in MCP server for AI-powered cost analysis through VSCode and GitHub Copilot.

Setup:

1. Add "chat.mcp.enabled": true to VSCode settings
2. Build ccExplorer: make build
3. Use with Copilot Chat in Agent Mode

Example queries:

@agent What were my AWS costs for the last 30 days grouped by service?
@agent Show my EC2 costs for the last quarter, excluding discounts

See VSCode MCP Integration Guide for details.

System Defaults

Setting	Default
Date range	Current calendar month
Cost metric	UnblendedCost
Output	stdout (table)
Sort order	Cost descending
Excluded charges	Credits, refunds, discounts (use -l to include)

Development

make build       # Build to bin/
make test        # Run tests
make lint        # Run linter
make release     # Create release with goreleaser

Contributing

Contributions welcome! We value bug fixes, documentation improvements, and new features.

This project uses Conventional Commits.

License

MIT