https://github.com/elc0mpa/aws-doctor
Diagnose AWS costs, detect idle resources, and optimize cloud spending directly from your terminal. 🩺 ☁️
https://github.com/elc0mpa/aws-doctor
aws aws-billing aws-cli aws-cost-explorer aws-doctor aws-trusted-advisor cli go golang
Last synced: about 2 months ago
JSON representation
Diagnose AWS costs, detect idle resources, and optimize cloud spending directly from your terminal. 🩺 ☁️
- Host: GitHub
- URL: https://github.com/elc0mpa/aws-doctor
- Owner: elC0mpa
- License: mit
- Created: 2025-08-30T14:57:45.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-02-01T19:10:16.000Z (4 months ago)
- Last Synced: 2026-02-02T01:34:56.693Z (4 months ago)
- Topics: aws, aws-billing, aws-cli, aws-cost-explorer, aws-doctor, aws-trusted-advisor, cli, go, golang
- Language: Go
- Homepage:
- Size: 17.7 MB
- Stars: 277
- Watchers: 3
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# aws-doctor
A terminal-based tool that acts as a comprehensive health check for your AWS accounts. Built with Golang, **aws-doctor** diagnoses cost anomalies, detects idle resources, and provides a proactive analysis of your cloud infrastructure.
> [!TIP]
> **View the full documentation, permissions guide, and usage examples at [awsdoctor.compacompila.com](https://awsdoctor.compacompila.com/)**
## 👀 Quick glance
### ⚖️ Comparative Cost Analytics
### 📈 6-Month Trend Analysis
### 🧟 Waste Detection
*Supports selective scanning: `aws-doctor waste ec2 s3 cloudwatch rds vpc lambda sagemaker elb ecr`*
## 📄 Professional Reporting
`aws-doctor` can now generate detailed, professional PDF reports ready for stakeholders. Reports include branded headers, styled tables, and comprehensive cost/waste analyses.
> [!TIP]
> **View PDF reporting examples and details at [awsdoctor.compacompila.com/docs/reporting/](https://awsdoctor.compacompila.com/docs/reporting/)**
### Generate a Cost Comparison Report
```bash
aws-doctor report cost
```
### Generate a Waste Analysis Report
```bash
# Full waste report
aws-doctor report waste
# Selective checks (e.g., ec2, s3, and lambda only)
aws-doctor report waste ec2 s3 lambda sagemaker
```
### Generate a Trend Report
```bash
# Full trend report (all services)
aws-doctor report trend
# Selective services (e.g., ec2 and rds only)
aws-doctor report trend ec2 rds
```
> [!TIP]
> **Subcommand Arguments:** Just like the terminal commands, `report waste` accepts specific checks (e.g., `ec2`, `s3`, `rds`, `lambda`) and `report trend` accepts specific service names.
> [!TIP]
> By default, reports are saved in your **Documents** folder. Use the `--path` flag to specify a custom directory or filename:
> `aws-doctor report cost --path ./billing-analysis.pdf`
## 🚀 Installation
**Homebrew (macOS/Linux):**
```bash
brew install elC0mpa/homebrew-tap/aws-doctor
```
**One-Line Script (macOS/Linux):**
```bash
curl -sSfL https://raw.githubusercontent.com/elC0mpa/aws-doctor/main/install.sh | sh
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/elC0mpa/aws-doctor/main/install.ps1 | iex
```
**Using Go:**
```bash
go install github.com/elC0mpa/aws-doctor@latest
```
## ✨ Key Features
- **📄 Professional PDF Reports:** Generate branded, ready-to-share PDF documents for costs, trends, and waste analysis.
- **📉 Fair Cost Comparison:** Compares identical time windows between months to spot real anomalies.
- **🧟 Zombie Discovery:** Scans for idle EIPs, stopped instances, orphaned snapshots, idle RDS instances, idle NAT Gateways, idle Load Balancers, over-provisioned Lambda memory, idle SageMaker real-time inference endpoints, and ECR repositories with untagged images, missing lifecycle policies, or no images at all. Supports selective service filtering (`ec2`, `s3`, `elb`, `cloudwatch`, `rds`, `vpc`, `lambda`, `sagemaker`, `ecr`).
- **📊 6-Month Trends:** High-fidelity ANSI visualization of your spending velocity.
- **📤 Multiple Output Formats:** Export results in `table`, `json`, or `csv` for easy integration with other tools or reporting.
- **🔔 Update Notifications:** Automatically checks for new versions in the background and notifies you after command output, so you never miss an update.
- **🔐 MFA Ready:** Native support for profiles requiring Multi-Factor Authentication.
- **🌍 Region-Aware Pricing:** Queries the AWS Pricing API at startup to use rates for the configured region, falling back to us-east-1 defaults if the API is unavailable. Requires `pricing:GetProducts` in the caller's IAM policy; without it, estimates silently fall back to defaults.
## 💡 Motivation
As a Cloud Architect, I often need to check AWS costs and billing information. While the AWS Console provides raw data, it lacks the immediate context I need to answer the question: *_"Are we spending efficiently?"_*
I created ***\*aws-doctor\**** to fill that gap. It doesn't just show you the bill; it acts as a diagnostic tool that helps you understand ***\*where\**** the money is going and ***\*what\**** can be cleaned up. It automates the routine checks I used to perform manually, serving as a free, open-source alternative to the paid recommendations found in AWS Trusted Advisor.
## 👥 Community
### Contributors
A huge thank you to everyone who has contributed to **aws-doctor**! Your help makes this tool better for everyone.
### Star History
## 🤝 Contributing
We love contributions! Whether it's a new detection rule or a bug fix, check our [Community Dashboard](https://awsdoctor.compacompila.com/#join-the-community) to get started.
> [!IMPORTANT]
> **Always target your Pull Requests to the `development` branch.** The `main` branch is reserved for production-ready releases. Check our [Contributing Guidelines](CONTRIBUTING.md) for more details.