@sriinnu/runic 1.0.0

package/docs/cli-commands/quick_reference.md

@@ -0,0 +1,362 @@
+# Runic CLI Commands - Quick Reference
+
+Quick reference guide for all Runic CLI tracking commands.
+
+## Command Overview
+
+| Command | Purpose | Key Options |
+|---------|---------|-------------|
+| `models` | Model usage breakdown | `--provider`, `--days`, `--by-project` |
+| `projects` | Project tracking | `--list`, `--stats`, `--sort-name` |
+| `alerts` | Usage alerts | `--active`, `--history`, `--clear` |
+| `reset` | Reset timings | `--when`, `--all`, `--compact` |
+| `usage-enhanced` | Enhanced usage | `--mode`, `--compare`, `--projected` |
+
+## Global Options
+
+Available on all commands:
+- `--json`, `-j` - JSON output
+- `--pretty` - Pretty-print JSON
+- `--no-color` - Disable colors
+- `--help`, `-h` - Show help
+
+## Command Details
+
+### runic models
+
+Show which AI models were used and their token consumption.
+
+```bash
+# Basic usage
+runic models
+
+# Filter by provider
+runic models --provider claude
+runic models -p codex
+
+# Time range
+runic models --days 7
+runic models -d 30
+
+# Group by project
+runic models --by-project
+
+# JSON output
+runic models --json --pretty
+```
+
+**Output:** Table showing model name, provider, tokens, requests, and cost.
+
+---
+
+### runic projects
+
+Track usage across different projects and codebases.
+
+```bash
+# List all projects
+runic projects
+runic projects --list
+runic projects -l
+
+# Show stats for specific project
+runic projects --stats my-project-id
+runic projects -s my-project-id
+
+# Sort options
+runic projects --sort-name     # Alphabetical
+runic projects --sort-tokens   # By usage (default)
+
+# Filter
+runic projects --provider claude --days 7
+```
+
+**Output:**
+- List mode: Table of all projects
+- Stats mode: Detailed project breakdown
+
+---
+
+### runic alerts
+
+Manage usage threshold alerts.
+
+```bash
+# Show active alerts
+runic alerts
+runic alerts --active
+runic alerts -a
+
+# View history
+runic alerts --history
+runic alerts -h
+
+# Clear resolved alerts
+runic alerts --clear
+runic alerts -c
+
+# Filter by provider
+runic alerts --provider claude
+runic alerts -p codex
+```
+
+**Output:** List of alerts with severity levels.
+
+**Alert Levels:**
+- ✗ Critical (>90% used) - Red
+- ⚠ Warning (>75% used) - Yellow
+- ℹ Info (>50% used) - Cyan
+
+---
+
+### runic reset
+
+Show when usage limits reset.
+
+```bash
+# Show all providers
+runic reset
+runic reset --all
+runic reset -a
+
+# Specific provider
+runic reset --when claude
+runic reset -w codex
+
+# Compact output
+runic reset --compact
+runic reset -c
+
+# JSON output
+runic reset --json --pretty
+```
+
+**Output:** Reset times and countdown for each provider window.
+
+**Status Indicators:**
+- ✓ Healthy (<50% used) - Green
+- ◐ Moderate (50-75%) - Cyan
+- ⚠ Warning (75-90%) - Yellow
+- ✗ Critical (>90%) - Red
+
+---
+
+### runic usage-enhanced
+
+Enhanced usage display with analytics.
+
+```bash
+# Display modes
+runic usage-enhanced                      # Summary (default)
+runic usage-enhanced --mode summary       # Quick overview
+runic usage-enhanced --mode detailed      # Full breakdown
+runic usage-enhanced --mode breakdown     # Token types
+runic usage-enhanced --mode trending      # Historical trends
+
+# Options
+runic usage-enhanced --show-cost          # Include costs
+runic usage-enhanced --projected          # Show projections
+runic usage-enhanced --compare            # Compare providers
+
+# Time range for trending
+runic usage-enhanced --mode trending --days 30
+
+# Filter by provider
+runic usage-enhanced --provider claude -m detailed
+```
+
+**Display Modes:**
+- **summary**: Quick overview with progress bars
+- **detailed**: Full window breakdown with reset times
+- **breakdown**: Token type analysis (input/output/cache)
+- **trending**: Historical usage trends
+
+---
+
+## Common Workflows
+
+### Daily Usage Check
+```bash
+# Quick summary
+runic usage-enhanced
+
+# Check for alerts
+runic alerts
+
+# See when limits reset
+runic reset --compact
+```
+
+### Weekly Analysis
+```bash
+# Last 7 days by model
+runic models --days 7 --json > models-weekly.json
+
+# Project breakdown
+runic projects --days 7
+
+# Trending analysis
+runic usage-enhanced --mode trending --days 7
+```
+
+### Project Tracking
+```bash
+# List all projects
+runic projects --list
+
+# Detailed project stats
+runic projects --stats my-project
+
+# Models used in project
+runic models --days 30 | grep my-project
+```
+
+### Cost Monitoring
+```bash
+# Enhanced usage with costs
+runic usage-enhanced --mode detailed --show-cost
+
+# Models by cost
+runic models --json | jq 'sort_by(.cost)'
+
+# Alert when high usage
+runic alerts --active
+```
+
+### Export for Analysis
+```bash
+# Export all data to JSON
+runic models --json --pretty > models.json
+runic projects --json --pretty > projects.json
+runic reset --json --pretty > reset-times.json
+
+# Trending data
+runic usage-enhanced --mode trending --days 30 --json > trends.json
+```
+
+## Output Formats
+
+### Text Output (Default)
+
+Colorized tables with:
+- Headers in cyan
+- High usage in red/yellow
+- Healthy usage in green
+- Progress bars for visualization
+
+### JSON Output
+
+Structured data for:
+- Scripting and automation
+- Data processing
+- Integration with other tools
+- Long-term storage
+
+Use `--json` for compact JSON
+Use `--json --pretty` for formatted JSON
+
+## Tips and Tricks
+
+### 1. Pipe to jq for JSON Processing
+```bash
+runic models --json | jq '.[] | select(.provider=="claude")'
+```
+
+### 2. Watch for Changes
+```bash
+watch -n 60 'runic alerts --active'
+```
+
+### 3. Create Aliases
+```bash
+alias runic-check='runic usage-enhanced && runic alerts'
+alias runic-weekly='runic models --days 7'
+```
+
+### 4. Combine with Other Tools
+```bash
+# Export to CSV
+runic models --json | jq -r '.[] | [.model, .tokens, .cost] | @csv'
+
+# Send alerts via notification
+runic alerts --active | mail -s "Usage Alerts" user@example.com
+```
+
+### 5. Scripting Examples
+```bash
+#!/bin/bash
+# Check if usage is critical
+ALERTS=$(runic alerts --json | jq 'map(select(.severity >= 3)) | length')
+if [ "$ALERTS" -gt 0 ]; then
+    echo "Critical usage alerts detected!"
+    runic alerts --active
+fi
+```
+
+## Troubleshooting
+
+### No data available
+- Check provider credentials
+- Verify usage logs exist
+- Try `--days` with larger value
+
+### Colors not working
+- Use `--no-color` flag
+- Check terminal supports ANSI codes
+- Set `TERM` environment variable
+
+### Slow performance
+- Reduce `--days` range
+- Use `--provider` to filter
+- Consider caching results
+
+### JSON parsing errors
+- Use `--pretty` for debugging
+- Validate with `jq`
+- Check command syntax
+
+## Environment Variables
+
+Set these for customization:
+```bash
+export RUNIC_NO_COLOR=1           # Disable colors
+export RUNIC_DEFAULT_DAYS=30      # Default time range
+export RUNIC_DEFAULT_FORMAT=json  # Default output format
+```
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Error (invalid arguments, no data, etc.)
+
+## Getting Help
+
+```bash
+# Global help
+runic --help
+
+# Command-specific help
+runic models --help
+runic projects --help
+runic alerts --help
+runic reset --help
+runic usage-enhanced --help
+```
+
+## Version Information
+
+```bash
+runic --version
+```
+
+## Additional Resources
+
+- Full documentation: See README.md
+- Integration guide: See INTEGRATION_GUIDE.md
+- Source code: Sources/RunicCLI/Commands/
+- Examples: Check command help text
+
+---
+
+**Last Updated:** 2026-01-31
+**Runic CLI Version:** 1.0.0

package/docs/cli-commands/readme.md

@@ -0,0 +1,361 @@
+# Runic CLI Commands
+
+This directory contains the new tracking commands for the Runic CLI, providing enhanced usage monitoring and analytics capabilities.
+
+## Commands Overview
+
+### 1. ModelsCommand.swift
+**Command:** `runic models`
+
+Shows which AI models were used across different providers, with token consumption and cost breakdown.
+
+**Features:**
+- Filter by provider
+- Time-based filtering (last N days)
+- JSON output support
+- Colorized table output
+- Group by project option
+
+**Examples:**
+```bash
+# Show all models used in the last 30 days
+runic models
+
+# Filter by provider
+runic models --provider claude --days 7
+
+# Group by project with JSON output
+runic models --by-project --json --pretty
+```
+
+### 2. ProjectsCommand.swift
+**Command:** `runic projects`
+
+Track usage across different projects and codebases.
+
+**Features:**
+- List all projects with summary stats
+- Detailed stats for specific projects
+- Sort by tokens or name
+- Provider filtering
+- JSON output support
+
+**Examples:**
+```bash
+# List all projects
+runic projects
+
+# Show detailed stats for a specific project
+runic projects --stats my-project-id
+
+# Filter by provider and time
+runic projects --provider claude --days 7 --sort-name
+```
+
+### 3. AlertsCommand.swift
+**Command:** `runic alerts`
+
+Manage usage threshold alerts to monitor token consumption.
+
+**Features:**
+- Show active alerts
+- View alert history
+- Clear resolved alerts
+- Provider-specific alerts
+- Severity levels (critical, warning, info)
+
+**Examples:**
+```bash
+# Show active alerts
+runic alerts
+
+# View alert history
+runic alerts --history
+
+# Filter by provider
+runic alerts --provider claude
+
+# Clear resolved alerts
+runic alerts --clear
+```
+
+### 4. ResetCommand.swift
+**Command:** `runic reset`
+
+Display when usage limits reset for different providers.
+
+**Features:**
+- Show reset times for all providers
+- Provider-specific reset info
+- Compact or detailed output
+- Status indicators
+- Time remaining calculations
+
+**Examples:**
+```bash
+# Show reset times for all providers
+runic reset
+
+# Show specific provider reset info
+runic reset --when claude
+
+# Compact output
+runic reset --compact --no-color
+```
+
+### 5. EnhancedUsageCommand.swift
+**Command:** `runic usage-enhanced`
+
+Enhanced version of the usage command with analytics and trending.
+
+**Features:**
+- Multiple display modes (summary, detailed, breakdown, trending)
+- Historical trending analysis
+- Cost projections
+- Provider comparison
+- Projected usage calculations
+
+**Examples:**
+```bash
+# Quick summary
+runic usage-enhanced --mode summary
+
+# Detailed breakdown with cost
+runic usage-enhanced --mode detailed --show-cost
+
+# Show 30-day trends
+runic usage-enhanced --mode trending --days 30
+
+# Compare providers
+runic usage-enhanced --compare --json
+```
+
+## Integration with CLIEntry.swift
+
+To integrate these commands into the main CLI, update `/Users/srinivaspendela/Sriinnu/AI/Runic/Sources/RunicCLI/CLIEntry.swift`:
+
+### Step 1: Import the Commands
+
+Add at the top of CLIEntry.swift:
+```swift
+// Import new command modules
+import struct Commands.ModelsCommand
+import struct Commands.ProjectsCommand
+import struct Commands.AlertsCommand
+import struct Commands.ResetCommand
+import struct Commands.EnhancedUsageCommand
+```
+
+### Step 2: Register Command Descriptors
+
+Add the descriptors to the Program initialization (around line 77):
+
+```swift
+let program = Program(descriptors: [
+    usageDescriptor,
+    costDescriptor,
+    insightsDescriptor,
+    // Add new commands
+    ModelsCommand.descriptor,
+    ProjectsCommand.descriptor,
+    AlertsCommand.descriptor,
+    ResetCommand.descriptor,
+    EnhancedUsageCommand.descriptor,
+])
+```
+
+### Step 3: Handle Command Invocations
+
+Add cases to the switch statement (around line 82):
+
+```swift
+switch invocation.descriptor.name {
+case "usage":
+    await self.runUsage(invocation)
+case "cost":
+    await self.runCost(invocation)
+case "insights":
+    await self.runInsights(invocation)
+case "models":
+    await ModelsCommand.run(invocation)
+case "projects":
+    await ProjectsCommand.run(invocation)
+case "alerts":
+    await AlertsCommand.run(invocation)
+case "reset":
+    await ResetCommand.run(invocation)
+case "usage-enhanced":
+    await EnhancedUsageCommand.run(invocation)
+default:
+    Self.exit(code: 1, message: "Unknown command")
+}
+```
+
+### Step 4: Update Help Text
+
+Update the `printHelp` function to include the new commands:
+
+```swift
+private static func printHelp(for command: String?) {
+    // ... existing help text ...
+
+    if command == "models" || command == nil {
+        print("models - Show model usage breakdown across providers")
+        print("  Options:")
+        print("    --provider, -p PROVIDER  Filter by provider")
+        print("    --days, -d DAYS          Number of days to analyze (default: 30)")
+        print("    --json, -j               Output in JSON format")
+        print("    --pretty                 Pretty-print JSON output")
+        print("    --no-color               Disable ANSI colors")
+        print("    --by-project             Group results by project")
+    }
+
+    if command == "projects" || command == nil {
+        print("projects - Track usage across different projects")
+        print("  Options:")
+        print("    --stats, -s PROJECT      Show stats for specific project")
+        print("    --provider, -p PROVIDER  Filter by provider")
+        print("    --days, -d DAYS          Number of days to analyze")
+        print("    --json, -j               Output in JSON format")
+        print("    --pretty                 Pretty-print JSON output")
+        print("    --sort-tokens            Sort by token usage (default)")
+        print("    --sort-name              Sort alphabetically")
+    }
+
+    if command == "alerts" || command == nil {
+        print("alerts - Manage usage threshold alerts")
+        print("  Options:")
+        print("    --provider, -p PROVIDER  Filter alerts by provider")
+        print("    --active, -a             Show only active alerts")
+        print("    --history, -h            Show alert history")
+        print("    --clear, -c              Clear resolved alerts")
+        print("    --json, -j               Output in JSON format")
+    }
+
+    if command == "reset" || command == nil {
+        print("reset - Show when usage limits reset")
+        print("  Options:")
+        print("    --when, -w PROVIDER      Show reset for specific provider")
+        print("    --all, -a                Show all providers (default)")
+        print("    --compact, -c            Show compact output")
+        print("    --json, -j               Output in JSON format")
+    }
+
+    if command == "usage-enhanced" || command == nil {
+        print("usage-enhanced - Enhanced usage display with analytics")
+        print("  Options:")
+        print("    --mode, -m MODE          Display mode: summary|detailed|breakdown|trending")
+        print("    --provider, -p PROVIDER  Filter by provider")
+        print("    --days, -d DAYS          Number of days for trending (default: 7)")
+        print("    --show-cost              Include cost information")
+        print("    --projected              Show projected usage")
+        print("    --compare                Compare usage across providers")
+    }
+}
+```
+
+## Common Features
+
+All commands share these common features:
+
+### Output Formats
+- **Text**: Human-readable, colorized output (default)
+- **JSON**: Machine-readable output with `--json` flag
+- **Pretty JSON**: Formatted JSON with `--pretty` flag
+
+### Color Support
+- Automatic color detection
+- Disable with `--no-color` flag
+- Color coding based on severity/usage levels:
+  - Green: Healthy/low usage
+  - Yellow: Warning/medium usage
+  - Red: Critical/high usage
+  - Cyan: Headers and highlights
+  - Magenta: Very high usage
+
+### Error Handling
+- Clear error messages to stderr
+- Non-zero exit codes on failure
+- Helpful error descriptions
+
+## File Structure
+
+```
+Sources/RunicCLI/Commands/
+├── README.md                    # This file
+├── ModelsCommand.swift          # Model usage breakdown (287 lines)
+├── ProjectsCommand.swift        # Project tracking (402 lines)
+├── AlertsCommand.swift          # Usage alerts (388 lines)
+├── ResetCommand.swift           # Reset timing info (364 lines)
+└── EnhancedUsageCommand.swift   # Enhanced usage display (479 lines)
+```
+
+## Implementation Notes
+
+### Design Patterns
+- **Enum-based commands**: Each command is a public enum with static methods
+- **Configuration structs**: Internal configuration parsing
+- **Helix integration**: Uses CommandSignature and CommandDescriptor
+- **Async/await**: All data loading is asynchronous
+- **Type safety**: Leverages Swift's type system
+
+### Dependencies
+- **RunicCore**: Core models and data fetchers
+- **Helix**: Command-line argument parsing
+- **Foundation**: Standard Swift library
+
+### Data Sources
+- **Live API**: Fetches current usage from provider APIs
+- **Usage Logs**: Reads historical data from local logs
+- **Aggregators**: Uses UsageLedgerAggregator for analytics
+
+## Testing
+
+### Manual Testing
+```bash
+# Build the CLI
+swift build
+
+# Test each command
+.build/debug/RunicCLI models
+.build/debug/RunicCLI projects --list
+.build/debug/RunicCLI alerts
+.build/debug/RunicCLI reset --all
+.build/debug/RunicCLI usage-enhanced --mode summary
+
+# Test JSON output
+.build/debug/RunicCLI models --json --pretty
+```
+
+### Integration Testing
+Test the commands work with existing CLI infrastructure:
+1. Help text display
+2. Unknown command handling
+3. Error messages
+4. Exit codes
+5. Color output
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Persistent Alert Storage**: Store alert history in a database
+2. **Custom Thresholds**: Allow users to set custom alert thresholds
+3. **Export Capabilities**: Export data to CSV, Excel, etc.
+4. **Visualization**: ASCII charts for trending data
+5. **Budget Tracking**: Set and track spending budgets
+6. **Notifications**: Integration with notification systems
+7. **Report Generation**: Automated usage reports
+8. **Multi-language Support**: i18n for help text and messages
+
+## License
+
+These commands are part of the Runic project and follow the same license as the main project.
+
+## Support
+
+For issues or questions:
+1. Check this README
+2. Review the command help text with `--help`
+3. Check the main Runic documentation
+4. File an issue in the project repository