claude-cost-cli

从命令行查询 Claude API 使用情况和成本报告。管理 API 密钥的安全 macOS 钥匙串存储。表/JSON 输出。

# 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`](https://github.com/cyberash-dev/claude-cost-cli/blob/main/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`](https://github.com/cyberash-dev/claude-cost-cli/blob/main/src/infrastructure/anthropic-usage-repository.ts) and [`src/infrastructure/anthropic-cost-repository.ts`](https://github.com/cyberash-dev/claude-cost-cli/blob/main/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](https://platform.claude.com/docs/en/build-with-claude/usage-cost-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

---

## 中文说明

# claude-cost-cli

一个用于查询 Anthropic Admin API 使用量和成本数据的命令行工具。需要从 Claude Console → Settings → Admin Keys 获取的 Admin API 密钥（`sk-ant-admin...`）。凭据存储在 macOS 钥匙串（Keychain）中。

## 安装

需要 Node.js >= 18 和 macOS。该软件包完全开源，采用 MIT 许可证：https://github.com/cyberash-dev/claude-cost-cli

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

该 npm 包发布时附带来源证明（provenance attestation），通过 GitHub Actions 将每个发行版与其源提交关联起来。你可以在安装前验证已发布的内容：
```bash
npm pack claude-cost-cli --dry-run
```

从源码安装（如果你希望在运行前审查代码）：
```bash
git clone https://github.com/cyberash-dev/claude-cost-cli.git
cd claude-cost-cli
npm install && npm run build && npm link
```

安装完成后，`claude-cost` 命令将全局可用。

## 快速开始

```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 密钥管理

存储 API 密钥（交互式掩码提示，校验 `sk-ant-admin` 前缀）：
```bash
claude-cost config set-key
```

显示已存储的密钥（掩码显示）：
```bash
claude-cost config show
```

从钥匙串中移除密钥：
```bash
claude-cost config remove-key
```

## 使用量报告

```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 输出（用于脚本编写）：
```bash
claude-cost usage --json
claude-cost usage --period 30d --json
```

输出列：Date、Model、Input Tokens、Cached Tokens、Output Tokens、Web Searches。

## 成本报告

```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 输出（用于脚本编写）：
```bash
claude-cost cost --json
claude-cost cost --sum --json
```

输出列：