Claude Cost 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 required binaries, storage method, and runtime instructions are consistent with a macOS CLI that queries Anthropic/Claude Admin API usage and costs; nothing requested or instructed appears disproportionate to that purpose.

Purpose & Capability

Name/description (Claude cost/usage CLI) match the artifacts: it requires the 'claude-cost' CLI and node, documents using an Anthropic Admin API key, and describes Keychain storage and usage/cost endpoints — these requirements are expected for this purpose.

Instruction Scope

SKILL.md only instructs installation of the CLI (npm or from source), running the 'claude-cost' commands, and storing the Admin API key in macOS Keychain. It does not ask the agent to read unrelated files, access other credentials, or transmit data to endpoints outside api.anthropic.com per the documented behavior.

Install Mechanism

This is an instruction-only skill (no code bundled). The README suggests installing via npm (npm install -g claude-cost-cli) or building from the GitHub repo — installing from npm is a common, moderate-risk supply-chain operation. Registry metadata shows no enforced install spec, but SKILL.md includes an npm install path and a GitHub source link; verify the package provenance and source before installing.

Credentials

No environment variables or unrelated credentials are requested. The only secret required is an Anthropic Admin API key (stored in macOS Keychain), which is proportional to querying organization usage/cost data.

Persistence & Privilege

The skill does not request persistent 'always' inclusion, does not modify other skills or system-wide agent settings, and limits storage to a Keychain entry (per the docs). Autonomous model invocation is allowed by default but is not combined with broad privileges here.

Assessment

This skill appears internally consistent for a macOS CLI that queries Anthropic/Claude usage and costs. Before installing: 1) Verify the npm package and GitHub repository (check the provenance attestation or review the source code) to reduce supply-chain risk; 2) Confirm the Admin API key you provide is the intended read-only Admin usage key and understand who can generate/revoke it in your organization; 3) Prefer installing from audited source (git clone + npm build) if you need higher assurance; 4) Remember the CLI will store the key in macOS Keychain — review that entry if you later revoke access; 5) Because the skill runs an external binary (claude-cost), only install/run it on machines you trust. If you need greater assurance, ask the publisher for a signed release or an audit of the repository.

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

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:

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

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

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

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):

claude-cost config set-key

Show stored key (masked):

claude-cost config show

Remove key from Keychain:

claude-cost config remove-key

Usage Reports

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):

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

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

Cost Reports

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):

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 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 and 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, 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