--- name: claude-usage-cli-d70094027919 description: Query Claude API usage and cost reports from the command line. Secure macOS Keychain storage for Admin API key. Table/JSON output. metadata: {"clawdbot":{"emoji":"📊","os":["macos"],"requires":{"bins":["claude-usage","node"]},"install":[{"id":"npm","kind":"shell","command":"npm install -g claude-usage-cli","bins":["claude-usage"],"label":"Install claude-usage-cli via npm"}],"source":"https://github.com/cyberash-dev/claude-usage-cli"}} --- # claude-usage-cli ⚠️ **DEPRECATED** — This skill is no longer maintained. Please use [`claude-cost-cli`](https://clawhub.com/skills/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 ```bash npm install -g claude-usage-cli ``` Install from source (if you prefer to audit the code before running): ```bash 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 ```bash 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): ```bash claude-usage config set-key ``` Show stored key (masked): ```bash claude-usage config show ``` Remove key from Keychain: ```bash claude-usage config remove-key ``` ## Usage Reports ```bash 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): ```bash claude-usage usage --json claude-usage usage --period 30d --json ``` Output columns: Date, Model, Input Tokens, Cached Tokens, Output Tokens, Web Searches. ## Cost Reports ```bash 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): ```bash 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 ` | Start date (YYYY-MM-DD or ISO) | 7 days ago | | `--to ` | End date (YYYY-MM-DD or ISO) | now | | `--period ` | Shorthand period (7d, 30d, 90d) | 7d | | `--model ` | Filter by model(s), comma-separated | all | | `--api-keys ` | Filter by API key ID(s), comma-separated | all | | `--group-by ` | Group by model, api_key_id, workspace_id, service_tier | model | | `--bucket ` | Bucket width: 1d, 1h, 1m | 1d | | `--json` | Output as JSON | false | ### `cost` | Flag | Description | Default | |------|-------------|---------| | `--from ` | Start date (YYYY-MM-DD or ISO) | 7 days ago | | `--to ` | End date (YYYY-MM-DD or ISO) | now | | `--period ` | Shorthand period (7d, 30d, 90d) | 7d | | `--group-by ` | 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 --- Source attribution: modbender Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/claude-usage-cli/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 skill-library-mcp contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: modbender Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/claude-usage-cli/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Data & Analytics, Development & Engineering Roles: Data Analyst, ML / AI Engineer, Technical Writer Specialties: API Tools: Claude, Macos, Node Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 56723e91be7587e21638c20166ef506a52605bdb468b42fb89e6e7c0aaa9cbd2