AWS FinOps Dashboard (CLI) v2.3.0

The AWS FinOps Dashboard is an open-source, Python-based command-line tool (built with the Rich library) for AWS cost monitoring. It provides multi-account cost summaries by time period, service, and cost allocation tags; budget limits vs. actuals; EC2 instance status; six‑month cost trend charts; and “FinOps audit” reports (e.g. untagged or idle resources). It can export data to CSV/JSON/PDF.

Why AWS FinOps Dashboard?

Managing and understanding your AWS expenditure, especially across multiple accounts and services, can be complex. The AWS FinOps Dashboard CLI aims to simplify this by providing a clear, concise, and actionable view of your AWS costs and operational hygiene directly in your terminal.

Key features include:

• Unified View: Consolidate cost and resource data from multiple AWS accounts.
• Cost Trend Analysis: View how your AWS costs have been for the past six months.
• Audit Your AWS Accounts: Quickly identify spending patterns, untagged resources, underutilised resources and potential savings.
• Generate Cost & Audit Reports: You can generate Cost, Trend and Audit Reports in PDF, CSV & JSON formats for further analysis and reporting purposes.
• Slack Integration: You can send your cost and audit reports to your Slack workspace in CSV/PDF/JSON formats.

Quick Start

Get up and running in under a minute:

# Install
pipx install aws-finops-dashboard

# View cost dashboard for your default AWS profile
aws-finops --region us-east-1

# View cost dashboard for specific profiles
aws-finops --profiles dev prod --region us-east-1

# View cost trends for the last 6 months
aws-finops --trend

# Run a FinOps audit
aws-finops --audit --region us-east-1

# Export to PDF
aws-finops --report-name my_report --report-type pdf

---

Table of Contents

• Quick Start
• Features
• Prerequisites
• Installation
• AWS CLI Profile Setup
• Command Line Usage
  • Options
  • Examples
• Using a Configuration File
  • TOML Configuration Example (config.toml)
  • YAML Configuration Example (config.yaml or config.yml)
  • JSON Configuration Example (config.json)
• Export Formats
• Cost For Every Run
• Contributing
• License

---

Features

• Cost Analysis by Time Period:
  • View current & previous month's spend by default
  • Set custom time ranges (e.g., 7, 30, 90 days) with --time-range option
  • Use --time-range last-month to query the previous calendar month (includes service breakdown for that month)
• Cost by AWS Service: Sorted by highest cost for better insights
• Cost by Tag: Get the cost data by one or more tags with --tag(cost allocation tags must be enabled)
• AWS Budgets Information: Displays budget limits and actual spend
• EC2 Instance Status: Detailed state information across specified/accessible regions
• Cost Trend Analysis: View detailed cost trends in bar charts for the last 6 months across AWS profiles
• FinOps Audit: View untagged resources, unused or stopped resources, and Budget breaches across AWS profiles.
• Profile Management:
  • Automatic profile detection
  • Specific profile selection with --profiles
  • Use all available profiles with --all
  • Combine profiles from the same AWS account with --combine
• Region Control: Specify regions for EC2 discovery using --regions
• Export Options:
  • CSV export with --report-name and --report-type csv
  • JSON export with --report-name and --report-type json
  • PDF export with --report-name and --report-type pdf
  • Export to multiple formats with --report-name and --report-type csv json pdf
  • Specify output directory using --dir
  • Export to S3 with --s3-bucket and --s3-profile
  • Export to Slack channel with --slack (requires SLACK_BOT_TOKEN environment variable)
  • Note: Trend reports (generated via --trend) currently only support JSON export. Other formats specified in --report-type will be ignored for trend reports.
• Improved Error Handling: Resilient and user-friendly error messages
• : Styled with the Rich library for a visually appealing experience

---

Prerequisites

• Python 3.8 or later: Ensure you have the required Python version installed
• AWS CLI configured with named profiles: Set up your AWS CLI profiles for seamless integration
• AWS credentials with permissions:
  • ce:GetCostAndUsage
  • budgets:ViewBudget
  • ec2:DescribeInstances
  • ec2:DescribeRegions
  • sts:GetCallerIdentity
  • ec2:DescribeVolumes
  • ec2:DescribeAddresses
  • rds:DescribeDBInstances
  • rds:ListTagsForResource
  • lambda:ListFunctions
  • lambda:ListTags
  • elbv2:DescribeLoadBalancers
  • elbv2:DescribeTags
  • s3:PutObject (required when using --s3-bucket to export reports to S3)
  • s3:ListBucket (required when using --s3-bucket to export reports to S3)

---

Installation

There are several ways to install the AWS FinOps Dashboard:

Option 1: Using pipx (Recommended)

pipx install aws-finops-dashboard

If you don't have pipx, install it with:

python -m pip install --user pipx
python -m pipx ensurepath

Option 2: Using pip

pip install aws-finops-dashboard

Option 3: Using uv (Fast Python Package Installer)

uv is a modern Python package installer and resolver that's extremely fast.

# Install uv if you don't have it yet
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create project directory
mkdir aws-finops-dashboard && cd aws-finops-dashboard

# Create and activate python virtual environment
uv venv && source .venv/bin/activate

# Install aws-finops-dashboard
uv pip install aws-finops-dashboard

Option 4: From Source

# Clone the repository
git clone https://github.com/ravikiranvm/aws-finops-dashboard.git
cd aws-finops-dashboard

# Create and activate python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install using pip
pip install -e .

Option 5: Using Docker

git clone https://github.com/ravikiranvm/aws-finops-dashboard.git
cd aws-finops-dashboard
docker compose build

# Run commands
docker compose run --rm aws-finops --all
docker compose run --rm aws-finops --profiles dev prod --regions us-east-1
docker compose run --rm aws-finops --audit

Note: AWS credentials are mounted from ~/.aws automatically via docker-compose.yml.

---

AWS CLI Profile Setup

If you haven't already, configure your named profiles using the AWS CLI:

aws configure --profile profile1-name
aws configure --profile profile2-name
# ... etc ...

Repeat this for all the profiles you want the dashboard to potentially access.

---

Slack Setup (Optional)

To send reports to Slack, you need to:

1. Create a Slack App and Bot Token:

   • Go to https://api.slack.com/apps
   • Create a new app or select an existing one
   • Navigate to "OAuth & Permissions"
   • Add Bot Token Scopes:
     • files:write (to upload files)
     • chat:write (to send messages)
   • Install the app to your workspace
   • Copy the "Bot User OAuth Token" (starts with xoxb-)

2. Set the Environment Variable:

   export SLACK_BOT_TOKEN=xoxb-your-token-here
   

3. Use the --slack flag with a channel identifier:

   • Channel ID: --slack C1234567890

Note:

• The token must be set as an environment variable (SLACK_BOT_TOKEN). It cannot be provided via config file or CLI flag for security reasons.
• Your app's bot user needs to be in the channel (otherwise, you will get either not_in_channel or channel_not_found error code).

---

Command Line Usage

Run the script using aws-finops followed by options:

aws-finops [options]

Command Line Options

Flag	Description
--config-file, -C	Path to a TOML, YAML, or JSON configuration file. Command-line arguments will override settings from the config file.
--profiles, -p	Specific AWS profiles to use (space-separated). If omitted, uses 'default' profile if available, otherwise all profiles.
--regions, -r	Specific AWS regions to check for EC2 instances (space-separated). If omitted, attempts to check all accessible regions.
--all, -a	Use all available AWS profiles found in your config.
--combine, -c	Combine profiles from the same AWS account into single rows.
--tag, -g	Filter cost data by one or more cost allocation tags in Key=Value format. Example: --tag Team=DevOps Env=Prod
--report-name, -n	Specify the base name for the report file (without extension).
--report-type, -y	Specify report types (space-separated): 'csv', 'json', 'pdf'. All formats are supported for both cost dashboard and audit reports. For trend reports, only 'json' is supported.
--dir, -d	Directory to save the report file(s) (default: current directory).
--time-range, -t	Time range for cost data in days (default: current month). Examples: 7, 30, 90. Use last-month to query the previous calendar month.
--trend	View cost trend analysis for the last 6 months.
--audit	View list of untagged, unused resources and budget breaches.
--s3-bucket, -s3	S3 bucket name to export report files to. When specified, files are uploaded to S3 instead of saving locally. Requires --s3-profile.
--s3-prefix, -s3p	S3 key prefix/folder path for report files (optional). Example: reports/2025/january

Examples

# Use default profile, show output in terminal only
aws-finops

# Use specific profiles 'dev' and 'prod'
aws-finops --profiles dev prod

# Use all available profiles
aws-finops --all

# Combine profiles from the same AWS account
aws-finops --all --combine

# Specify custom regions to check for EC2 instances
aws-finops --regions us-east-1 eu-west-1 ap-southeast-2

# View cost data for the last 30 days instead of current month
aws-finops --time-range 30

# View cost data only for a specific tag (e.g., Team=DevOps)
aws-finops --tag Team=DevOps

# View cost data for multiple tags (e.g., Team=DevOps and Env=Prod)
aws-finops --tag Team=Devops Env=Prod

# Export data to CSV only
aws-finops --all --report-name aws_dashboard_data --report-type csv

# Export data to JSON only
aws-finops --all --report-name aws_dashboard_data --report-type json

# Export data to both CSV and JSON formats simultaneously
aws-finops --all --report-name aws_dashboard_data --report-type csv json

# Export combi