claude-usage-cli

Query Claude API usage and cost reports from the command line. Secure macOS Keychain storage for Admin API key. Table/JSON output.

Security Scan

The skill's behavior (run a claude-usage CLI that stores an Admin API key in macOS Keychain and talks to api.anthropic.com) is plausible for its stated purpose, but there are mismatches and unverifiable claims you should review before installing — notably the package metadata does not declare the Admin API credential the SKILL.md requires.

Purpose & Capability

The SKILL.md clearly requires an Anthropic Admin API key (sk-ant-admin...) and describes storing it in macOS Keychain, but the registry metadata lists no required environment variables or primary credential. Requiring the 'claude-usage' and 'node' binaries is consistent with a CLI wrapper, however the omission of the Admin API credential in the skill metadata is an inconsistency that reduces transparency.

Instruction Scope

The runtime instructions are limited to installing/running a CLI (claude-usage) and using Keychain to store an Admin API key; they do not ask the agent to read arbitrary files or system state. However, the SKILL.md makes concrete claims about network scope (only contacting api.anthropic.com over HTTPS) and key handling (never written to disk in plaintext) that cannot be verified from an instruction-only skill with no code. Because the skill delegates behavior to an external binary, those claims should be validated by inspecting the CLI's code or package.

Install Mechanism

SKILL.md recommends installing via npm (npm install -g claude-usage-cli) or git-clone/build. npm/global install is a common but moderately risky install vector because it executes third-party code from the registry; the SKILL.md references a GitHub repo which is a good sign, but the registry metadata reported 'No install spec' — the presence of install instructions inside SKILL.md but not in the top-level install spec is an inconsistency to confirm. Verify the npm package and GitHub source before installing.

Credentials

The tool requires an Admin API key to query organization usage/costs. Admin keys can be sensitive/powerful; the skill metadata does not declare any required credential or primaryEnv, which is misleading. The SKILL.md asserts read-only scope for that key, but you should treat an Admin key as a high-privilege secret and prefer least-privilege tokens if available.

Persistence & Privilege

The skill is not force-included (always:false) and does not request persistent system-wide privileges. It stores the API key in the user's macOS Keychain (as documented) and claims not to write plaintext to disk. There is no evidence in the provided files that the skill modifies other skills or system settings.

What to consider before installing

Before installing: 1) Confirm the npm package and GitHub repository are legitimate (owner, recent commits, stars, issues) and inspect the CLI source — SKILL.md's claims about Keychain and network scope can only be validated by reading code. 2) Do not paste a high-privilege Admin key unless necessary — prefer a least-privilege/read-only token or an account that limits blast radius. 3) Verify the npm package tarball (npm view / integrity) or build from source (git clone) if you want to audit before executing. 4) Check that the CLI actually only connects to api.anthropic.com (monitor network activity on first run). 5) If you have low tolerance for risk, prefer alternatives with published source and active maintenance (SKILL.md even marks this skill DEPRECATED).

⚠️ DEPRECATED — This skill is no longer maintained. Please use claude-cost-cli instead, which provides the same functionality with active support.

---

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 open source: https://github.com/cyberash-dev/claude-usage-cli

npm install -g claude-usage-cli

Install from source (if you prefer to audit the code before running):

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

After installation the claude-usage command is available globally.

Quick Start

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

API Key Management

Store API key (interactive masked prompt, validates sk-ant-admin prefix):

claude-usage config set-key

Show stored key (masked):

claude-usage config show

Remove key from Keychain:

claude-usage config remove-key

Usage Reports

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

JSON output (for scripting):

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

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

Cost Reports

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

JSON output (for scripting):

claude-usage cost --json
claude-usage 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

• Admin API key: stored exclusively in macOS Keychain (service: claude-usage-cli). Never written to disk in plaintext.
• No config files: all settings are passed via CLI flags. Nothing is stored on disk besides the Keychain entry.
• Network: the API key is only sent to api.anthropic.com over HTTPS. No other outbound connections are made.
• 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.
• No caching: query results are not cached or persisted to disk.

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