AWS CostLens

AWS Cost Intelligence CLI Tool
Terminal-based dashboard for AWS cost monitoring, resource scanning, and report generation.

---

✨ Features

Feature	Description
💵 Cost Dashboard	Current vs previous period costs by service, budgets, EC2 summary
📈 Cost History	6-month trend visualization with month-over-month changes
🔍 Resource Scan	Find stopped instances, unused volumes, unattached EIPs, untagged resources
📄 Export Reports	PDF, CSV, JSON formats — structured and shareable
⏱️ Flexible Time Ranges	last-month, N days, or custom date ranges
🏷️ Tag Filtering	Filter costs by AWS cost allocation tags
🔧 Multi-Profile	Run across one, multiple, or all AWS CLI profiles
📋 YAML Config	Reusable configuration files
☁️ S3 Upload	Automatically upload reports to S3

---

🚀 Installation

From PyPI (recommended):

pip install devops-aws-costlens

Or with pipx (isolated):

pipx install devops-aws-costlens

Verify installation:

aws-costlens --version

---

📖 Quick Start

# Cost dashboard (default command)
aws-costlens --profiles <profile>

# Resource scan
aws-costlens scan --profiles <profile>

# 6-month cost history
aws-costlens history --profiles <profile>

---

⏱️ Time Range Options

CostLens supports flexible time range comparisons:

Option	Description	Example
(default)	Current month (MTD) vs last full month	aws-costlens --profiles mfa
last-month	Last full month vs prior full month	aws-costlens --profiles mfa --time-range last-month
N (days)	Last N days vs previous N days	aws-costlens --profiles mfa --time-range 30
YYYY-MM-DD:YYYY-MM-DD	Custom date range vs prior same-length window	aws-costlens --profiles mfa --time-range 2025-12-01:2026-01-01

Examples:

# Last 7 days vs previous 7 days (spike detection)
aws-costlens --profiles mfa --time-range 7

# Full December 2025 vs November 2025
aws-costlens --profiles mfa --time-range last-month

# Last 90 days vs previous 90 days
aws-costlens --profiles mfa --time-range 90

---

🏷️ Tag Filtering

Filter costs by AWS cost allocation tags:

# Single tag
aws-costlens --profiles mfa --tag Project=CDS

# Multiple tags (AND logic)
aws-costlens --profiles mfa --tag Project=CDS --tag Environment=prod

Note: Cost allocation tags must be activated in AWS Billing for tag-based filtering to work.

---

📤 Export Reports

Scan Reports (PDF, CSV, JSON)

aws-costlens scan --profiles <profile> --format csv --name scan-report
aws-costlens scan --profiles <profile> --format pdf csv json --name scan-report

History Reports (JSON only)

aws-costlens history --profiles <profile> --format json --name history-report

Cost Dashboard Reports (PDF, CSV, JSON, XLSX)

aws-costlens export --profiles <profile> --format pdf --name cost-report
aws-costlens export --profiles <profile> --format csv json xlsx --name cost-report

Complete Report Pack

# Dashboard + Scan + History in all formats
aws-costlens export --profiles <profile> --scan --history --format pdf csv json xlsx --name full-report

---

🔧 Commands Reference

cost — Cost Dashboard (default)

aws-costlens [cost] --profiles <profile> [options]

Options:
  --profiles, -p      AWS CLI profile names
  --all-profiles, -a  Use all configured profiles
  --merge             Merge results from same account
  --time-range, -t    last-month | N days | YYYY-MM-DD:YYYY-MM-DD
  --tag               Filter by tag (key=value)
  --config, -c        YAML config file

history — 6-Month Cost History

aws-costlens history --profiles <profile> [options]

Options:
  --profiles, -p      AWS CLI profile names
  --all-profiles, -a  Use all configured profiles
  --format, -f        json (for export)
  --name, -n          Report file name (required with --format)
  --dir, -d           Output directory

scan — Resource Scan

aws-costlens scan --profiles <profile> [options]

Options:
  --profiles, -p      AWS CLI profile names
  --all-profiles, -a  Use all configured profiles
  --regions, -r       Specific regions (default: all accessible)
  --format, -f        pdf | csv | json (for export)
  --name, -n          Report file name (required with --format)
  --dir, -d           Output directory

Scan checks:

• ⏹️ Stopped EC2 instances
• 💾 Unattached EBS volumes
• 🌐 Unused Elastic IPs
• 🏷️ Untagged resources (EC2, RDS, Lambda, ELBv2)

export — Generate Reports

aws-costlens export --profiles <profile> [options]

Options:
  --profiles, -p      AWS CLI profile names
  --all-profiles, -a  Use all configured profiles
  --merge             Merge results from same account
  --time-range, -t    last-month | N days | YYYY-MM-DD:YYYY-MM-DD
  --tag               Filter by tag (key=value)
  --format, -f        pdf | csv | json | xlsx (default: pdf)
  --name, -n          Report file name (default: costlens_report)
  --dir, -d           Output directory
  --scan              Include resource scan
  --history           Include cost history
  --bucket            S3 bucket for upload
  --s3-path           S3 prefix

---

📋 Configuration File

Create costlens.yaml for reusable settings:

profiles:
  - dev
  - staging
  - prod

regions:
  - us-east-1
  - eu-west-1

name: monthly_report
format:
  - pdf
  - csv

dir: ./reports
merge: false

Usage:

aws-costlens --config costlens.yaml
aws-costlens export --config costlens.yaml

CLI arguments override config file settings.

---

🔐 AWS Permissions

CostLens uses read-only AWS APIs. Required permissions:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ce:GetCostAndUsage",
      "budgets:DescribeBudgets",
      "ec2:DescribeInstances",
      "ec2:DescribeVolumes",
      "ec2:DescribeAddresses",
      "ec2:DescribeRegions",
      "rds:DescribeDBInstances",
      "rds:ListTagsForResource",
      "lambda:ListFunctions",
      "lambda:ListTags",
      "elasticloadbalancing:DescribeLoadBalancers",
      "elasticloadbalancing:DescribeTags",
      "sts:GetCallerIdentity",
      "s3:PutObject"
    ],
    "Resource": "*"
  }]
}

s3:PutObject is only needed if uploading reports to S3.

---

🐳 Docker

# Build
docker build -t aws-costlens .

# Run with AWS credentials
docker run -v ~/.aws:/root/.aws:ro aws-costlens --profiles default

Docker Compose:

docker compose run costlens --profiles prod
docker compose run costlens scan --all-profiles
docker compose run costlens export --all-profiles --format pdf csv

---

📸 Screenshots

Screenshots coming soon...

---

📦 From Source

git clone https://github.com/Calza36/aws-costlens.git
cd aws-costlens
pip install -e .

---

📄 License

MIT License — see LICENSE file.

Inspired by aws-finops-dashboard

---

Author: Ernesto Calzadilla Martínez
GitHub · PyPI