claude-usage-cli

⚠️ 已弃用 — 此功能不再维护。请改用 claude-cost-cli，它提供相同功能并享有持续支持。

一款用于查询 Anthropic Admin API 的用量与成本数据的命令行工具。需从 Claude Console → Settings → Admin Keys 获取 Admin API 密钥（格式为 sk-ant-admin...）。凭据将存储于 macOS Keychain 中。

安装

要求 Node.js >= 18 且运行于 macOS 系统。本项目为开源软件：https://github.com/cyberash-dev/claude-usage-cli

npm install -g claude-usage-cli

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

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

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

快速开始

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

API 密钥管理

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

claude-usage config set-key

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

claude-usage config show

从 Keychain 中移除密钥：

claude-usage config remove-key

用量报告

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

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

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

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

成本报告

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

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

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

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

参数参考

usage

cost

安全与数据存储

• Admin API 密钥：仅存储于 macOS Keychain（服务名：claude-usage-cli），绝不会以明文形式写入磁盘。
• 无配置文件：所有设置均通过 CLI 参数传入；除 Keychain 条目外，不向磁盘写入任何内容。
• 网络通信：API 密钥仅通过 HTTPS 发送至 api.anthropic.com；不建立其他任何出站连接。
• 权限范围：Admin API 密钥仅具备组织用量与成本数据的只读访问权限，无法修改账单设置、创建 API 密钥，亦无法访问对话内容。
• 无缓存机制：查询结果既不缓存，也不持久化至磁盘。

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