readme.md

aws-cost-cli

CLI tool to perform cost analysis on your AWS account with Slack integration

Installation

Install the package globally or alternatively you can also use npx

npm install -g aws-cost-cli

Usage

For the simple usage, just run the command without any options.

aws-cost

The output will be the totals with breakdown by service. Optionally, you can pass the following options to modify the output:

$ aws-cost --help

  Usage: aws-cost [options]

  A CLI tool to perform cost analysis on your AWS account

  Options:
    -V, --version                  output the version number

    -k, --access-key [key]         AWS access key
    -s, --secret-key [key]         AWS secret key
    -t, --session-token [key]      AWS session token
    -r, --region [region]          AWS region (default: us-east-1)
    -a, --role-arn [arn]           AWS role ARN to assume

    -T, --target-account [id]      Account ID to see cost
    -p, --profile [profile]        AWS profile to use (default: "default")

    -j, --json                     Get the output as JSON
    -u, --summary                  Get only the summary without service breakdown
    -t, --text                     Get the output as plain text (no colors / tables)

    -S, --slack-token [token]      Slack token for the slack message
    -C, --slack-channel [channel]  Slack channel to post the message to
    -P, --breakdown-period [period] Unit period to show service breakdown (yesterday|last7Days|thisMonth|lastMonth)')

    -v, --version                  Get the version of the CLI
    -h, --help                     Get the help of the CLI

In order to use the CLI you can either pass the AWS credentials through the options i.e.:

aws-cost -k [key] -s [secret] -r [region]

or if you have configured the credentials using aws-cli, you can simply run the following command:

aws-cost

To configure the credentials using aws-cli, have a look at the aws-cli docs for more information.

If you need to assume a role, you can pass the role-arn option:

aws-cost -a arn:aws:iam::123456789012:role/your-role-arn

If you need to query cost info of another account under your organization, you can pass the --target-account option:

aws-cost --target-account 123456789012

Detailed Breakdown

The default usage is to get the cost breakdown by service

aws-cost

You will get the following output

Total Costs

You can also get the summary of the cost without the service breakdown

aws-cost --summary

You will get the following output

Plain Text

You can also get the output as plain text

aws-cost --text

You will get the following output in response

JSON Output

You can also get the output as JSON

aws-cost --json

You will get the following output in response

{
  "account": "theroadmap",
  "totals": {
    "lastMonth": 0.38,
    "thisMonth": 11.86,
    "last7Days": 1.29,
    "yesterday": 0.22
  },
  "totalsByService": {
    "lastMonth": {
      "AmazonCloudWatch": 0,
      "Tax": 0,
      "AWS Key Management Service": 0,
      "AWS Service Catalog": 0,
      "Amazon Simple Email Service": 0.38,
      "Amazon Simple Notification Service": 0,
      "Amazon Simple Storage Service": 0.00001
    },
    "thisMonth": {
      "AmazonCloudWatch": 0,
      "Tax": 0,
      "AWS Key Management Service": 0,
      "AWS Service Catalog": 0,
      "Amazon Simple Email Service": 11.85,
      "Amazon Simple Notification Service": 0,
      "Amazon Simple Storage Service": 0
    },
    "last7Days": {
      "AmazonCloudWatch": 0,
      "Tax": 0,
      "AWS Key Management Service": 0,
      "AWS Service Catalog": 0,
      "Amazon Simple Email Service": 1.28,
      "Amazon Simple Notification Service": 0,
      "Amazon Simple Storage Service": 0
    },
    "yesterday": {
      "AmazonCloudWatch": 0,
      "Tax": 0,
      "AWS Key Management Service": 0,
      "AWS Service Catalog": 0,
      "Amazon Simple Email Service": 0.22,
      "Amazon Simple Notification Service": 0,
      "Amazon Simple Storage Service": 0
    }
  }
}

Slack Integration

You can also get the output as a slack message

aws-cost --slack-token [token] --slack-channel [channel]

You will get the message on slack with the breakdown:

You can set up a GitHub workflow similar to this which can send the daily cost breakdown to Slack.

Note

Regarding the credentials, you need to have the following permissions in order to use the CLI:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "iam:ListAccountAliases",
        "ce:GetCostAndUsage"
      ],
      "Resource": "*"
    }
  ]
}

If you need to use Role-Based Access Control (RBAC), you will need to configure two IAM roles: the provider role and the consumer role.

1. Provider Role

This role provides the necessary permissions for aws-cost-cli. It requires the above permissions policy and the following trust policy.

Trust Policy

Replace arn:aws:iam::YOUR_ACCOUNT_ID:role/YourConsumerRole with the ARN of the consumer role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:role/YourConsumerRole"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

2. Consumer Role

This role is used by the user or service (such as GitHub Actions) that needs to assume the provider role to access cost information. It requires the following permissions policy.

Permissions Policy

Replace arn:aws:iam::YOUR_ACCOUNT_ID:role/YourProviderRole with the ARN of the provider role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::YOUR_ACCOUNT_ID:role/YourProviderRole"
    }
  ]
}

Please also note that this tool uses AWS Cost Explorer under the hood which costs $0.01 per request.

License

MIT © Kamran Ahmed