awsce

Check, summarize and analyze your AWS costs from the command line.

Why

The AWS console is slow when you only want a quick answer:

• What did we spend this month, and on which services?
• Which usage type inside EC2 costs the most?
• How do five accounts compare, side by side?
• Where can we save money right now?

awsce answers these from your terminal, using the AWS credentials you already have. When you need to share the answer, it exports CSV, JSON or a self-contained HTML report.

Install

Requires Python 3.10 or newer.

pipx install awsce        # or: pip install awsce
awsce --version

From source:

git clone https://github.com/hoangbeard/awsce.git
cd awsce
pip install -e .

Quick start

# This month so far, for your default profile
awsce costs

# Last month, saved as an HTML report
awsce costs --start 2026-09-01 --end 2026-10-01 -o september.html

# Compare several accounts, grouped by service
awsce costs -p dev -p staging -p prod --view services

# Where can we save money?
awsce optimize rightsizing -r us-east-1 -r eu-west-1
awsce optimize hub

Commands

Run any command with --help to see all options.

Periods

--start is the first day. --end is the day after the last day, the same way Cost Explorer works. So --start 2026-09-01 --end 2026-10-01 is all of September.

With no dates, awsce shows the current month so far. On the 1st of a month, it shows last month instead.

Many accounts

Use one profile per account:

awsce costs -p dev -p prod              # chosen profiles
awsce costs --all-profiles              # every profile in ~/.aws/config

Then pick how to see them with --view:

If one profile fails, for example an expired SSO session, awsce warns you and goes on with the rest.

If you use AWS Organizations, you can also run awsce costs once with the management account. Cost Explorer there already includes every member account.

Small amounts

Rows under $0.01 are hidden by default to keep the output short. Totals always include them. Add --detail to see every row. Credits and refunds (negative amounts) are always shown.

Export

Add -o FILE. The format follows the extension:

Savings recommendations

# Compute Optimizer: EC2, Auto Scaling, EBS, Lambda, RDS, ECS on Fargate
awsce optimize rightsizing -r us-east-1 --type ec2 --type ebs --min-savings 10

# Every member account, from the management account
awsce optimize rightsizing -p management --organization

# Cost Optimization Hub: rightsizing, Savings Plans, Reserved Instances and more
awsce optimize hub --type Ec2Instance --limit 20

Both services must be turned on in your account first: Compute Optimizer and Cost Optimization Hub.

Cost and caching

Cost Explorer charges $0.01 for each API request. To keep this low, awsce caches results on your machine:

Use --refresh to skip the cache, or --cache-hours to change how long it lasts. The cache lives in ~/.cache/awsce (or $AWSCE_CACHE_DIR).

Permissions

awsce only reads. A minimal IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Costs",
      "Effect": "Allow",
      "Action": ["ce:GetCostAndUsage", "ce:GetDimensionValues"],
      "Resource": "*"
    },
    {
      "Sid": "Recommendations",
      "Effect": "Allow",
      "Action": [
        "compute-optimizer:GetEC2InstanceRecommendations",
        "compute-optimizer:GetAutoScalingGroupRecommendations",
        "compute-optimizer:GetEBSVolumeRecommendations",
        "compute-optimizer:GetLambdaFunctionRecommendations",
        "compute-optimizer:GetRDSDatabaseRecommendations",
        "compute-optimizer:GetECSServiceRecommendations",
        "cost-optimization-hub:ListRecommendations",
        "organizations:ListAccounts"
      ],
      "Resource": "*"
    }
  ]
}

Compute Optimizer also needs read access to the resources it reports on. The AWS managed policy ComputeOptimizerReadOnlyAccess covers this.

Security notes

• awsce never writes to your AWS account.
• Credentials come from the normal AWS chain (profiles, SSO, environment variables). awsce never stores them, and error output never prints them.
• Cache files hold account IDs and cost data. They are readable only by you (mode 600).
• HTML reports escape every name that comes from AWS. CSV exports guard against spreadsheet formula injection.
• HTML reports load Chart.js from a CDN, pinned with a Subresource Integrity hash.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

pytest              # tests use botocore Stubber, no AWS account needed
ruff check . && ruff format --check .
mypy src

License

MIT © Pham Huy Hoang (HoangBeard)