claude-usage-cli

claude-usage-cli 是一款面向开发者和运维团队的命令行工具，专为查询 Anthropic Claude API 的用量和成本数据而设计。通过调用 Anthropic Admin API，用户可以快速获取组织级别的 token 使用详情和费用 breakdown，支持按日期范围、模型类型、API key ID 等多维度筛选和分组。工具采用 macOS Keychain 安全存储 Admin API 密钥，确保凭证不会以明文形式写入磁盘，同时仅通过 HTTPS 与 api.anthropic.com 通信，保障数据传输安全。

该工具的核心优势在于其简洁高效的命令行交互体验和灵活的数据输出格式。用户可通过 claude-usage usage 和 claude-usage cost 命令分别查询用量和成本，支持表格和 JSON 两种输出格式，便于集成到自动化脚本或数据分析流程中。时间维度支持从小时级到月级的灵活配置（通过 --bucket 参数），且提供 --sum 选项快速获取总成本。此外，工具仅申请只读权限的 Admin API key，无法修改配置或访问对话内容，从权限层面降低了安全风险。

然而，用户需特别注意该工具已被官方标记为 DEPRECATED，不再维护，建议使用 claude-cost-cli 替代。功能层面，该 CLI 仅支持 macOS 系统，且依赖 Node.js 运行环境（>= 18），跨平台兼容性受限。对于需要长期稳定支持的生产环境，当前弃用状态构成了显著风险。此外，虽然工具本身不缓存数据，但 Admin API key 涉及组织级财务敏感信息，一旦泄露可能导致用量数据被恶意获取。

该技能主要适合以下群体：使用 Claude API 进行产品开发的技术团队、需要监控 AI 支出的财务管理员、以及负责成本优化的 DevOps 工程师。对于希望快速了解 API 消耗模式或生成定期成本报告的用户尤为实用。但鉴于其已弃用状态，建议仅作为参考文档了解 Anthropic Admin API 的功能边界，实际生产使用应迁移至替代方案。

使用风险方面，除上述维护状态风险外，还包括：Node.js 运行时和 npm 包的供应链安全风险（尽管可从源码审计后安装）；Admin API key 的管理责任完全落在用户端，需确保 Keychain 安全；网络层面的单点依赖（仅支持 Anthropic 官方 API）。建议用户在非生产环境测试验证后再考虑使用，并严格遵循最小权限原则管理 API 密钥。

核心用法

本 Skill 为 claude-usage-cli 的命令行工具使用文档，用于查询 Anthropic Claude API 的用量和成本数据。用户需先从 Claude Console 获取 Admin API 密钥（格式 sk-ant-admin...），通过 claude-usage config set-key 交互式存储至 macOS Keychain。

主要功能分为三类：

• 配置管理：set-key/show/remove-key 管理 Keychain 中的 API 密钥
• 用量查询：usage 命令支持按日期范围、模型、API 密钥 ID 筛选，支持 1d/1h/1m 粒度聚合，可输出表格或 JSON
• 成本报表：cost 命令提供按描述、工作空间分组的费用明细，--sum 快速获取总支出

显著优点

1. 安全存储设计：API 密钥仅存放于 macOS Keychain，不落盘明文，符合企业安全合规要求
2. 灵活输出格式：原生支持 Table 可读格式与 JSON 结构化输出，便于脚本集成
3. 细粒度筛选：支持模型、API 密钥、工作空间、服务层级多维度分组聚合
4. 官方 API 封装：直接对接 Anthropic Admin API，数据权威可信

潜在缺点与局限性

⚠️ 关键提示：本 Skill 已标记 DEPRECATED，官方推荐迁移至 `claude-cost-cli`。

• 平台限制：仅支持 macOS，Linux/Windows 用户无法使用
• 外部依赖风险：实际功能依赖 npm 包 claude-usage-cli，该包由个人开发者维护（T3 来源），需单独审计源码
• 无主动维护：仓库可能停止更新，存在功能滞后或安全漏洞未修复风险
• 网络访问要求：必须允许出站 HTTPS 至 api.anthropic.com

适合人群

• Claude Enterprise 管理员：需要定期审计组织级 API 用量与账单
• DevOps/SRE 工程师：需将成本监控集成至现有观测体系（通过 JSON 输出）
• macOS 重度用户：已熟悉命令行工具链，具备 Node.js 环境

常规风险

• 密钥泄露：若 Keychain 被攻破或用户误执行恶意脚本，Admin API 密钥可能暴露（虽为只读权限，仍可导致敏感用量数据泄露）
• 供应链攻击：npm 包被篡改或依赖树引入恶意代码
• 数据隐私：用量报表包含模型调用模式，可能间接泄露业务规模与使用习惯
• 弃用迁移成本：当前 Skill 不再维护，需评估迁移至替代方案的工作量

安全评估结论

本 Skill 文档本身为纯 Markdown，无可执行代码，静态扫描通过。但实际功能完全依赖外部 CLI 工具，该工具由个人开发者发布，未经过企业级安全审计。建议生产环境使用前：
1. 优先采用官方推荐的 claude-cost-cli
2. 如必须使用，从源码编译安装并审计依赖树
3. 定期轮换 Admin API 密钥并监控调用日志