npm package: @secondcontext/cost-advisor-cli-agent
Description: Architecture-aware AWS cost optimization using your local Claude CLI
Latest version: 0.1.0

# cost-advisor-cli-agent

Architecture-aware AWS cost optimization powered by your local Claude CLI.

Fetches real AWS cost data, scans your infrastructure files, queries live resource inventory, then invokes Claude to produce ranked, actionable cost-reduction recommendations — with an interactive deep-dive menu to go deeper on any item.

## Usage

```bash
npx cost-advisor-cli-agent [options]
```

Or install globally:

```bash
npm install -g cost-advisor-cli-agent
cost-advisor-cli-agent [options]
```

## Options

| Flag | Description | Default |
|---|---|---|
| `--profile <name>` | AWS CLI profile to use (interactive picker if omitted) | `$AWS_PROFILE` or `default` |
| `--region <name>` | AWS region | `$AWS_REGION` or `us-east-1` |
| `--infra-dir <path>` | Directory to scan for Terraform/CDK/CloudFormation files | `.` (current dir) |
| `--no-infra` | Skip infrastructure file scanning | — |
| `--dry-run` | Print the Claude prompt without invoking it | — |
| `--claude-path <path>` | Override path to the `claude` binary | auto-detected |
| `-h, --help` | Show help | — |

## Examples

```bash
# Interactive profile picker
npx cost-advisor-cli-agent

# Specify profile directly
npx cost-advisor-cli-agent --profile my-aws-profile

# Point at your infrastructure directory
npx cost-advisor-cli-agent --profile my-aws-profile --infra-dir ./infrastructure

# See the prompt that would be sent without calling Claude
npx cost-advisor-cli-agent --profile my-aws-profile --dry-run
```

## Prerequisites

1. **AWS CLI** — configured with a profile that has these permissions:
   - `ce:GetCostAndUsage`
   - `ce:GetCostForecast`
   - `ecs:ListClusters`, `ecs:ListServices`, `ecs:ListTasks`
   - `rds:DescribeDBInstances`, `rds:DescribeDBClusters`
   - `ec2:DescribeInstances`, `ec2:DescribeNatGateways`
   - `elasticache:DescribeCacheClusters`
   - `lambda:ListFunctions`
   - `s3:ListBuckets`
   - `sts:GetCallerIdentity`
   - *(optional)* `organizations:ListAccounts` for multi-account support
   - *(optional)* `sts:AssumeRole` for cross-account inventory

2. **Claude CLI** — install from https://claude.ai/download

## What it does

1. Fetches 4 weeks of AWS Cost Explorer data (with week-over-week trend analysis)
2. Scans your working directory for infrastructure files (Terraform `.tf`, CDK, CloudFormation)
3. Queries live AWS resource inventory across ECS, RDS, EC2, Lambda, ElastiCache, S3, and more
4. For AWS Organizations management accounts: automatically enumerates linked accounts, fetches per-account costs, and assumes `OrganizationAccountAccessRole` in each account to collect cross-account inventory
5. Renders an ASCII cost trend chart and top services bar chart
6. Invokes Claude with all context to generate **5 ranked cost-reduction recommendations**
7. Opens an interactive menu to deep-dive into any recommendation or ask custom questions

## Multi-account support

If your AWS profile is an **Organizations management account**, the tool automatically:
- Lists all linked accounts via `organizations:ListAccounts`
- Fetches per-account cost breakdowns
- Assumes `OrganizationAccountAccessRole` in each linked account to collect resource inventory
- Provides Claude with a full cross-account view

## Environment variables

| Variable | Description |
|---|---|
| `AWS_PROFILE` | Default AWS profile (overridden by `--profile`) |
| `AWS_REGION` | Default region (overridden by `--region`) |
| `NO_COLOR=1` | Disable ANSI color output |