Claude Cost Cli

# claude-cost-cli

A CLI for querying Anthropic Admin API usage and cost data. Requires an Admin API key (`sk-ant-admin...`) from Claude Console → Settings → Admin Keys. Credentials are stored in macOS Keychain.

Installation

Requires Node.js >= 18 and macOS. The package is fully open source under the MIT license: https://github.com/cyberash-dev/claude-cost-cli

```bash npm install -g claude-cost-cli ```

The npm package is published with provenance attestation, linking each release to its source commit via GitHub Actions. You can verify the published contents before installing: ```bash npm pack claude-cost-cli --dry-run ```

Install from source (if you prefer to audit the code before running): ```bash git clone https://github.com/cyberash-dev/claude-cost-cli.git cd claude-cost-cli npm install && npm run build && npm link ```

After installation the `claude-cost` command is available globally.

Quick Start

```bash claude-cost config set-key # Interactive prompt: enter Admin API key (masked) claude-cost usage # Token usage for the last 7 days claude-cost cost # Cost breakdown for the last 7 days claude-cost cost --sum # Total spend for the last 7 days ```

API Key Management

Store API key (interactive masked prompt, validates `sk-ant-admin` prefix): ```bash claude-cost config set-key ```

Show stored key (masked): ```bash claude-cost config show ```

Remove key from Keychain: ```bash claude-cost config remove-key ```

Usage Reports

```bash claude-cost usage # Last 7 days, daily, grouped by model claude-cost usage --period 30d # Last 30 days claude-cost usage --from 2026-01-01 --to 2026-01-31 # Custom date range claude-cost usage --model claude-sonnet-4 # Filter by model claude-cost usage --api-keys apikey_01Rj,apikey_02Xz # Filter by API key IDs claude-cost usage --group-by model,api_key_id # Group by multiple dimensions claude-cost usage --bucket 1h # Hourly granularity (1d, 1h, 1m) ```

JSON output (for scripting): ```bash claude-cost usage --json claude-cost usage --period 30d --json ```

Output columns: Date, Model, Input Tokens, Cached Tokens, Output Tokens, Web Searches.

Cost Reports

```bash claude-cost cost # Last 7 days, grouped by description claude-cost cost --period 30d # Last 30 days claude-cost cost --from 2026-01-01 --to 2026-01-31 # Custom date range claude-cost cost --group-by workspace_id,description # Group by workspace and description claude-cost cost --sum # Total cost only ```

JSON output (for scripting): ```bash claude-cost cost --json claude-cost cost --sum --json ```

Output columns: Date, Description, Model, Amount (USD), Token Type, Tier.

Flag Reference

`usage` | Flag | Description | Default | |------|-------------|---------| | `--from <date>` | Start date (YYYY-MM-DD or ISO) | 7 days ago | | `--to <date>` | End date (YYYY-MM-DD or ISO) | now | | `--period <days>` | Shorthand period (7d, 30d, 90d) | 7d | | `--model <models>` | Filter by model(s), comma-separated | all | | `--api-keys <ids>` | Filter by API key ID(s), comma-separated | all | | `--group-by <fields>` | Group by model, api_key_id, workspace_id, service_tier | model | | `--bucket <width>` | Bucket width: 1d, 1h, 1m | 1d | | `--json` | Output as JSON | false |

`cost` | Flag | Description | Default | |------|-------------|---------| | `--from <date>` | Start date (YYYY-MM-DD or ISO) | 7 days ago | | `--to <date>` | End date (YYYY-MM-DD or ISO) | now | | `--period <days>` | Shorthand period (7d, 30d, 90d) | 7d | | `--group-by <fields>` | Group by workspace_id, description | description | | `--sum` | Output total cost only | false | | `--json` | Output as JSON | false |

Security and Data Storage

The following properties are by design and can be verified in the source code:

• Admin API key: stored exclusively in macOS Keychain (service: `claude-cost-cli`). By design, never written to disk in plaintext. See `src/infrastructure/keychain-credential-store.ts` for the implementation.
• No config files: all settings are passed via CLI flags. Nothing is stored on disk besides the Keychain entry.
• Network: by design, the API key is only sent to `api.anthropic.com` over HTTPS. No other outbound connections are made. See `src/infrastructure/anthropic-usage-repository.ts` and `src/infrastructure/anthropic-cost-repository.ts`.
• Scope: the Admin API key grants read-only access to organization usage and cost data. It cannot modify billing, create API keys, or access conversation content. This is a property of the Anthropic Admin API, not just this CLI.
• No caching: query results are not cached or persisted to disk. The CLI writes output to stdout only.

API Reference

• This CLI wraps the Anthropic Admin API:
• Usage: `GET /v1/organizations/usage_report/messages`
• Cost: `GET /v1/organizations/cost_report`

Documentation: https://platform.claude.com/docs/en/build-with-claude/usage-cost-api