---
roadcrew_template_name: "usage-report.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---
# /usage-report

Generate monthly token usage reports from AI command logs.

## Usage

```bash
/usage-report                  # Current month
/usage-report --month 2025-01  # Specific month
/usage-report --export csv     # Export to CSV
/usage-report --export json    # Export to JSON
```

## Description

Displays token usage breakdown by:
- **Command** - Which commands used most tokens
- **Project** - Usage per project (multi-repo mode)
- **User** - Team attribution

Includes cost estimates and quota tracking.

## Requirements

- **Tier**: Starter ($49/mo) or higher
- **Token tracking**: Must be enabled
- **Usage logs**: Must exist in `.analysis/token-usage.jsonl`

## Examples

### Current Month Report

```bash
/usage-report
```

Output:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 TOKEN USAGE REPORT - October 2025
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Usage:
  Tokens: 87,450 / 100,000 (87.5%)
  Cost: $4.37
  Status: ⚠️  Warning (approaching limit)

By Command:
  enrich-release       45,230 tokens ($2.26)  51.7%
  analyze-epic         28,100 tokens ($1.41)  32.1%
  classify-feedback    14,120 tokens ($0.71)  16.2%

By Project:
  frontend             32,100 tokens ($1.61)  36.7%
  backend              28,900 tokens ($1.45)  33.1%

By User:
  john@org.com         52,340 tokens ($2.62)  59.8%
  jane@org.com         35,110 tokens ($1.76)  40.2%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Historical Month

```bash
/usage-report --month 2025-09
```

### Export to CSV

```bash
/usage-report --export csv
```

Creates `.analysis/usage-report-2025-10.csv`

### Export to JSON

```bash
/usage-report --export json
```

Creates `.analysis/usage-report-2025-10.json`

## Configuration

Configure quota in `config/agent-config.yml`:

```yaml
token_tracking:
  max_tokens_per_month: 100000  # Starter: 100k
  warning_threshold: 0.8        # Warn at 80%
```

## Troubleshooting

**No usage data found**
- Run AI commands first to generate usage logs
- Check `.analysis/token-usage.jsonl` exists

**Invalid month format**
- Use YYYY-MM format (e.g., 2025-01)
- Month must be between 01 and 12

**Export failed**
- Ensure `.analysis/` directory exists
- Check write permissions

## Related Commands

- `/enrich-release` - AI-powered release enrichment
- `/analyze-epic` - Epic analysis with token tracking
- `/classify-feedback` - Feedback classification

## Related Files

- `scripts/usage-report.ts` - Report generator
- `scripts/utils/token-tracker.ts` - Usage logging
- `scripts/utils/cost-calculator.ts` - Cost estimation
- `.analysis/token-usage.jsonl` - Usage log file

---

**Tier**: Starter+  
**Epic**: #68 - Token Tracking Foundation  
**Issue**: #73