alibaba-cost

A CLI tool to perform cost analysis on your Alibaba Cloud account with Slack integration

Note: This tool defaults to international Alibaba Cloud accounts (alibabacloud.com). If you have a China domestic account (aliyun.com), use the --region cn-hangzhou flag or see TROUBLESHOOTING.md for more details.

Requirements

• Node.js 18.0.0 or higher (tested on 18.x, 20.x, 22.x, 25.x)
• Alibaba Cloud account with BSS API access
• RAM user with billing permissions (see Required Permissions)

Installation

Check your Node.js version:

node --version  # Should be 18.0.0 or higher

Install the package globally or use npx:

npm install -g alibaba-cost

# Or use npx without installation
npx alibaba-cost

Usage

For basic usage, run the command without any options:

alibaba-cost

The output displays totals with a breakdown by service.

You can use the following options to customize the output:

$ alibaba-cost --help

Usage: alibaba-cost [options]

A CLI tool to perform cost analysis on your Alibaba Cloud account

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

  -k, --access-key [key]         Alibaba Cloud access key
  -s, --secret-key [key]         Alibaba Cloud secret key
  -r, --region [region]          Alibaba Cloud BSS API region
                                 (ap-southeast-1 for international [default],
                                 cn-hangzhou for China)

  -p, --profile [profile]        Alibaba Cloud profile to use (default: "default")

  -j, --json                     Output in JSON format
  -u, --summary                  Show only summary without service breakdown
  -t, --text                     Output as plain text (no colors/tables)

  -S, --slack-token [token]      Slack bot token for notifications
  -C, --slack-channel [channel]  Slack channel ID for notifications

  -h, --help                     Display help information

Credentials

You can provide credentials in two ways:

1. Command-line options:

alibaba-cost -k [access-key] -s [secret-key] -r [region]

2. Configuration file:

Create a configuration file at ~/.aliyun/config.json:

{
  "profiles": [
    {
      "name": "default",
      "access_key_id": "your-access-key",
      "access_key_secret": "your-secret-key"
    }
  ]
}

Then simply run:

alibaba-cost

Region Configuration

The CLI automatically uses the correct endpoint based on the region:

• International accounts (default): No region flag needed, uses ap-southeast-1

  alibaba-cost

• China domestic accounts: Specify the region flag

  alibaba-cost --region cn-hangzhou

The tool automatically selects the appropriate BSS API endpoint based on your region.

Output Formats

Default (Colorful Table)

Display cost breakdown with colors and formatting:

alibaba-cost

Summary Only

Get only the totals without service breakdown:

alibaba-cost --summary

Plain Text

Get output as plain text without colors:

alibaba-cost --text

JSON Output

Get output in JSON format:

alibaba-cost --json

Example JSON output:

{
  "account": "my-account",
  "totals": {
    "lastMonth": 1250.48,
    "thisMonth": 892.35,
    "last7Days": 187.42,
    "yesterday": 28.56
  },
  "totalsByService": {
    "lastMonth": {
      "ECS": 650.25,
      "OSS": 320.18,
      "RDS": 280.05
    },
    "thisMonth": {
      "ECS": 485.30,
      "OSS": 225.15,
      "RDS": 181.90
    },
    "last7Days": {
      "ECS": 98.50,
      "OSS": 52.32,
      "RDS": 36.60
    },
    "yesterday": {
      "ECS": 14.25,
      "OSS": 8.16,
      "RDS": 6.15
    }
  }
}

Slack Integration

Send cost reports to Slack by creating a Slack app with chat:write and chat:write.public scopes.

Note: The --slack-channel parameter requires the channel ID, not the channel name.

alibaba-cost --slack-token [token] --slack-channel [channel-id]

You can automate daily cost reports using a GitHub Actions workflow or similar automation.

Required Permissions

To use this CLI, your Alibaba Cloud account needs the following permissions:

• bss:QueryInstanceBill - To retrieve billing data
• bss:GetAccountRelation - To fetch account information

You can grant the AliyunBSSReadOnlyAccess managed policy or create a RAM user with a custom policy containing these permissions.

Verify Permissions

Run the diagnostic script to check if your RAM user has the correct permissions:

node check-permissions.js

This will test your API access and provide specific guidance based on the results.

Having issues? Check the TROUBLESHOOTING.md guide for common errors and solutions.

Development

Build

npm run build

Run Tests

npm test

Watch Mode

npm run dev

Troubleshooting

Node.js Version Issues

If you see an error about incompatible Node.js version:

error [email protected]: The engine "node" is incompatible with this module.
Expected version ">=18.0.0". Got "16.x.x"

Solution: Upgrade to Node.js 18 or higher:

# Check current version
node --version

# Upgrade using nvm (recommended)
nvm install 18
nvm use 18

# Or download from https://nodejs.org/

Other Issues

For billing data errors, permission issues, and region configuration problems, see TROUBLESHOOTING.md.

License

MIT © Ilia Shakitko

Contributing

Issues and pull requests are welcome!