claude-cost-cli

一款用于查询 Anthropic Admin API 使用量与费用数据的命令行工具（CLI）。需从 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

npm install -g claude-cost-cli

该 npm 包已通过来源证明（provenance attestation）发布，借助 GitHub Actions 将每次发布与其源代码提交记录绑定。你可在安装前验证已发布的包内容：

npm pack claude-cost-cli --dry-run

如需在运行前审计源码，也可选择从源码安装：

git clone https://github.com/cyberash-dev/claude-cost-cli.git
cd claude-cost-cli
npm install && npm run build && npm link

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

快速开始

claude-cost config set-key     # 交互式提示：输入 Admin API 密钥（掩码显示）
claude-cost usage              # 过去 7 天的 Token 使用量
claude-cost cost               # 过去 7 天的费用明细
claude-cost cost --sum         # 过去 7 天的总支出

API 密钥管理

存储 API 密钥（交互式掩码输入，自动校验前缀 sk-ant-admin）：

claude-cost config set-key

查看已存储的密钥（掩码显示）：

claude-cost config show

从 Keychain 中移除密钥：

claude-cost config remove-key

使用量报告

claude-cost usage                                    # 过去 7 天，按天统计，按模型分组
claude-cost usage --period 30d                       # 过去 30 天
claude-cost usage --from 2026-01-01 --to 2026-01-31 # 自定义日期范围
claude-cost usage --model claude-sonnet-4            # 按模型过滤
claude-cost usage --api-keys apikey_01Rj,apikey_02Xz # 按 API 密钥 ID 过滤
claude-cost usage --group-by model,api_key_id        # 按多个维度分组
claude-cost usage --bucket 1h                        # 按小时粒度聚合（支持 1d、1h、1m）

JSON 输出（适用于脚本调用）：

claude-cost usage --json
claude-cost usage --period 30d --json

输出字段：日期、模型、输入 Token 数、缓存 Token 数、输出 Token 数、网络搜索次数。

费用报告

claude-cost cost                                           # 过去 7 天，按描述分组
claude-cost cost --period 30d                              # 过去 30 天
claude-cost cost --from 2026-01-01 --to 2026-01-31        # 自定义日期范围
claude-cost cost --group-by workspace_id,description       # 按工作区 ID 和描述分组
claude-cost cost --sum                                     # 仅输出总费用

JSON 输出（适用于脚本调用）：

claude-cost cost --json
claude-cost cost --sum --json

输出字段：日期、描述、模型、金额（USD）、Token 类型、层级（Tier）。

参数参考

usage

cost

安全性与数据存储

以下特性均为设计使然，且均可在源码中验证：

• Admin API 密钥：仅存储于 macOS Keychain（服务名：claude-cost-cli）。设计上绝不会以明文形式写入磁盘。实现详见 src/infrastructure/keychain-credential-store.ts。
• 无配置文件：所有设置均通过 CLI 参数传入；除 Keychain 条目外，不向磁盘写入任何其他内容。
• 网络通信：设计上，API 密钥仅通过 HTTPS 发送至 api.anthropic.com；不建立任何其他出站连接。详见 src/infrastructure/anthropic-usage-repository.ts 和 src/infrastructure/anthropic-cost-repository.ts。
• 权限范围：Admin API 密钥仅授予组织级用量与费用数据的只读访问权限，无法修改账单、创建 API 密钥，亦无法访问对话内容。此限制由 Anthropic Admin API 本身定义，并非本 CLI 独有。
• 无缓存机制：查询结果不会被缓存或持久化至磁盘；CLI 仅将输出写入 stdout。

API 参考

本 CLI 封装了 Anthropic Admin API：

• 用量接口：GET /v1/organizations/usage_report/messages
• 费用接口：GET /v1/organizations/cost_report

官方文档：https://platform.claude.com/docs/en/build-with-claude/usage-cost-api