Track and record AI token consumption per session, model, and provider. Logs input/output token counts, cache utilization, and rate-limit status for cost monitoring and quota management.
| Flag | Short | Description | Takes Value |
|---|---|---|---|
--branch | Git branch (default: auto-detect) | Yes | |
--cache-read | -cr | Number of tokens read from cache | Yes |
--cache-write | -cw | Number of tokens written to cache | Yes |
--help | -h | Show help message and exit | Yes |
--input | -i | Input token count for this request | Yes |
--model | -m | Model name (e.g. claude-sonnet-4-20250514) | Yes |
--output | -o | Output token count for this request | Yes |
--project | Project name (default: cwd basename) | Yes | |
--provider | -p | AI provider name (e.g. anthropic, openai) | Yes |
--rl-5h | Rate-limit 5-hour utilization (0.0–1.0) | Yes | |
--rl-7d | Rate-limit 7-day utilization (0.0–1.0) | Yes | |
--rl-claim | Rate-limit representative claim | Yes | |
--rl-overage | Rate-limit overage utilization (0.0–1.0) | Yes | |
--rl-status | Rate-limit status (allowed / throttled) | Yes | |
--session | -s | Session identifier for grouping usage | Yes |
--tier | -t | Subscription tier (e.g. free, pro, team) | Yes |
# Record a basic usage event with input/output tokens
scorpiox-usage --model claude-sonnet-4-20250514 --input 1500 --output 800 \
--provider anthropic --session abc123# Track cache-aware usage (cache read + cache write tokens)
scorpiox-usage -m claude-sonnet-4-20250514 -i 3200 -o 1100 -p anthropic \
-cr 2400 -cw 600 -s session-xyz# Log rate-limit status alongside token counts
scorpiox-usage -m claude-sonnet-4-20250514 -i 5000 -o 2000 -p anthropic \
--rl-status allowed --rl-5h 0.42 --rl-7d 0.18 \
--rl-overage 0.0 --rl-claim "200k tokens/5h"# Specify project and branch for multi-repo tracking
scorpiox-usage -m gpt-4o -i 800 -o 400 -p openai \
--project my-api-server --branch feature/auth \
--tier pro -s sess-9f1a# Minimal invocation — just token counts and model
scorpiox-usage -m claude-sonnet-4-20250514 -i 1024 -o 512# Full telemetry: tokens + cache + rate limits + metadata
scorpiox-usage \
--model claude-sonnet-4-20250514 \
--provider anthropic \
--input 12000 --output 4500 \
--cache-read 8000 --cache-write 1200 \
--session long-running-task \
--project scorpiox-code \
--branch main \
--tier team \
--rl-status allowed \
--rl-5h 0.67 --rl-7d 0.31 \
--rl-overage 0.0 \
--rl-claim "500k tokens/5h"