claude-usage-cli

⚠️ 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

CODEBLOCK0

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

After installation the claude-usage command is available globally.

Quick Start

CODEBLOCK2

API Key Management

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

Show stored key (masked):
CODEBLOCK4

Remove key from Keychain:
CODEBLOCK5

Usage Reports

CODEBLOCK6

JSON output (for scripting):
CODEBLOCK7

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

Cost Reports

CODEBLOCK8

JSON output (for scripting):
CODEBLOCK9

Output columns: Date, Description, Model, Amount (USD), Token Type, Tier.

Flag Reference

usage

Flag	Description	Default
INLINECODE5	Start date (YYYY-MM-DD or ISO)	7 days ago
INLINECODE6

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, apikeyid, workspaceid, servicetier | model | | --bucket <width> | Bucket width: 1d, 1h, 1m | 1d | | --json | Output as JSON | false |

cost

Flag	Description	Default
INLINECODE14	Start date (YYYY-MM-DD or ISO)	7 days ago
INLINECODE15

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: INLINECODE22
• Cost: INLINECODE23

Documentation: https://platform.claude.com/docs/en/build-with-claude/usage-cost-api