rird 2.1.231 → 2.3.0

package/docs/CLI_REFERENCE.md

@@ -0,0 +1,681 @@
+# RIRD CLI Reference
+
+Complete command-line interface reference for RIRD AI Agent.
+
+## Quick Reference
+
+```bash
+rird                          # Start interactive mode
+rird "task description"       # Run task once
+rird help                     # Show help
+rird --version                # Show version
+rird activate <key>           # Activate license
+rird status                   # Check license status
+```
+
+## Global Flags
+
+Flags that work with any command:
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--help`, `-h` | Show command help | `rird run --help` |
+| `--version`, `-v` | Show RIRD version and system info | `rird -v` |
+| `--debug` | Enable debug logging (verbose) | `DEBUG=1 rird <task>` |
+| `--quiet`, `-q` | Suppress non-essential output | `rird -q <task>` |
+| `--config <path>` | Use custom config file | `rird --config ~/custom.yaml <task>` |
+| `--no-color` | Disable colored output | `rird --no-color <task>` |
+| `--json` | Output as JSON (for scripting) | `rird --json <task>` |
+
+## Core Commands
+
+### rird
+
+Start RIRD interactive mode (TUI).
+
+```bash
+rird
+```
+
+**Usage**:
+- Opens interactive terminal UI
+- Enter task descriptions freely
+- View progress in real-time
+- Save conversations to disk
+- Navigate with keyboard shortcuts
+
+**Keyboard Shortcuts**:
+- `Ctrl+C` - Exit
+- `Ctrl+L` - Clear screen
+- `Ctrl+S` - Save conversation
+- `Ctrl+R` - Run task
+- `Tab` - Autocomplete
+- `Up/Down` - Navigate history
+
+**Example**:
+```bash
+$ rird
+RIRD AI Agent v2.1.239
+
+> Write a Python script that validates email addresses
+Agent is thinking...
+[Creates script.py]
+
+> Add unit tests for the email validator
+```
+
+### rird <task>
+
+Run a single task in non-interactive mode.
+
+```bash
+rird "Build a web scraper for news headlines"
+```
+
+**Usage**:
+- Execute task and exit
+- No interactive shell
+- Good for automation/scripts
+- Returns exit code (0=success, 1=failure)
+
+**Examples**:
+```bash
+# Simple task
+rird "What is the capital of France?"
+
+# Multi-line task (with newlines)
+rird "Create a function that:
+1. Reads a CSV file
+2. Filters for valid emails
+3. Exports to JSON"
+
+# With environment variables
+OPENAI_API_KEY=sk-... rird "Summarize this article"
+```
+
+**Exit Codes**:
+- `0` - Success
+- `1` - Task failed
+- `2` - Invalid arguments
+- `3` - License error
+- `4` - Configuration error
+- `5` - Network error
+
+### rird activate <key>
+
+Activate your RIRD license.
+
+```bash
+rird activate rird_abc123xyz
+```
+
+**Steps**:
+1. Get key from https://rird.ai/dashboard
+2. Run command with your key
+3. System validates and caches license
+4. Confirmation message shows plan details
+
+**Example Output**:
+```
+RIRD AI
+
+Activating license...
+License key saved
+Validating license...
+
+License activated!
+Welcome, user@example.com
+Plan: Pro
+
+Run 'rird' to get started
+```
+
+**Troubleshooting**:
+- Invalid key format? Ensure it starts with `rird_`
+- Network error? Check internet connection
+- Server unreachable? Try later or use offline mode
+
+### rird status
+
+Check current license status.
+
+```bash
+rird status
+```
+
+**Outputs**:
+
+**When Licensed**:
+```
+RIRD AI
+
+Status: Active
+Account: user@example.com
+Plan: Pro
+Cache expiry: 2026-01-15
+```
+
+**When Not Licensed**:
+```
+RIRD AI
+
+Status: Not activated
+
+Run: rird activate YOUR_LICENSE_KEY
+Get your key at: https://rird.ai
+```
+
+**Options**:
+- `--json` - Output as JSON for parsing
+
+**Example (JSON)**:
+```bash
+$ rird status --json
+{
+  "status": "active",
+  "email": "user@example.com",
+  "plan": "pro",
+  "cache_expiry": "2026-01-15",
+  "valid": true
+}
+```
+
+### rird help [command]
+
+Show help for a command or list all commands.
+
+```bash
+rird help                    # List all commands
+rird help run                # Show help for 'run' command
+rird help models             # Show help for 'models' command
+```
+
+**Output Example**:
+```
+RIRD AI - Help
+
+Commands:
+  rird                       Start interactive mode
+  rird <task>                Run a single task
+  rird activate <key>        Activate license
+  rird status                Check license status
+  rird models                List available models
+  rird upgrade               Update to latest version
+  rird health-check          Verify installation health
+  rird debug                 Show debug information
+
+Options:
+  --help, -h                 Show this help
+  --version, -v              Show version
+  --debug                    Enable debug logging
+  --config <path>            Use custom config file
+```
+
+## Advanced Commands
+
+### rird models
+
+List available AI models.
+
+```bash
+rird models
+```
+
+**Output**:
+```
+Available Models:
+
+Primary Models:
+  0000/ui-tars-1.5-7b:latest    Computer Vision & Browser Control
+  gpt-4-turbo                    Reasoning & Analysis
+  claude-3-opus                  General Purpose
+
+Fast Models:
+  gpt-3.5-turbo                 Speed Optimized
+  claude-3-haiku                Lightweight
+
+Vision Models:
+  gpt-4-vision                   Image Understanding
+  claude-3-vision                Document Analysis
+```
+
+**Options**:
+- `--json` - Output as JSON
+- `--filter <pattern>` - Filter models by pattern
+
+**Example**:
+```bash
+# List only vision models
+rird models --filter vision
+
+# Get JSON output for scripting
+rird models --json | jq '.models[0]'
+```
+
+### rird upgrade
+
+Update RIRD to the latest version.
+
+```bash
+rird upgrade
+```
+
+**Process**:
+1. Checks latest version online
+2. Downloads binary for your platform
+3. Replaces current binary
+4. Verifies installation
+5. Restarts command
+
+**Example**:
+```
+RIRD AI
+
+Upgrading to latest version...
+
+Downloading rird v2.1.240...
+Verifying checksums...
+Installing update...
+Updated to v2.1.240. Restarting...
+```
+
+**Options**:
+- `--dry-run` - Check for updates without installing
+- `--force` - Force upgrade even if already on latest
+- `--version <version>` - Upgrade to specific version
+
+### rird health-check
+
+Verify installation and dependencies.
+
+```bash
+rird health-check
+```
+
+**Checks**:
+- License validity
+- Python environment
+- MCP servers
+- Network connectivity
+- Configuration files
+- Disk space
+
+**Example Output**:
+```
+RIRD Health Check
+
+[OK] License valid (expires: 2026-06-15)
+[OK] Python 3.11.4 installed
+[OK] Required packages: httpx, loguru, PIL (3/3)
+[OK] MCP: stealth-browser-mcp running
+[OK] Network: Connected to rird.ai (45ms)
+[OK] Config file readable: ~/.rird/engine/config.yaml
+[OK] Disk space: 2.3GB available
+
+All systems operational. Ready to use.
+```
+
+**Exit Code**:
+- `0` - All checks passed
+- `1` - At least one check failed
+
+### rird debug
+
+Show detailed debug information.
+
+```bash
+rird debug [section]
+```
+
+**Sections**:
+- `all` - All debug information
+- `config` - Configuration settings
+- `license` - License details
+- `env` - Environment variables
+- `paths` - File paths and directories
+- `system` - System information
+
+**Examples**:
+```bash
+# Show all debug info
+rird debug
+
+# Show only system information
+rird debug system
+
+# Show configuration
+rird debug config
+```
+
+**Example Output (system)**:
+```
+System Information:
+
+Platform: darwin (macOS)
+Architecture: arm64
+Node Version: v18.17.0
+Python Version: 3.11.4
+Home Directory: /Users/example
+RIRD Home: /Users/example/.rird
+
+CPU:
+  Count: 8
+  Model: Apple M2
+
+Memory:
+  Total: 16GB
+  Available: 8.2GB
+
+Disk:
+  /: 450GB (82% used)
+  /Volumes/Data: 2TB (25% used)
+```
+
+### rird serve [options]
+
+Start RIRD API server for remote execution.
+
+```bash
+rird serve
+```
+
+**Starts HTTP server**:
+- Default port: `8765`
+- Protocol: REST API
+- Authentication: Bearer token
+
+**Endpoints**:
+- `POST /api/task` - Submit task
+- `GET /api/task/<id>` - Get task status
+- `GET /api/status` - License/health status
+- `GET /health` - Health check
+
+**Options**:
+- `--port <port>` - Custom port (default: 8765)
+- `--host <host>` - Bind address (default: localhost)
+- `--auth-token <token>` - Require auth token
+- `--ssl` - Enable HTTPS (requires cert)
+
+**Example**:
+```bash
+# Start server on port 9000 with auth
+rird serve --port 9000 --auth-token secret123
+
+# From another machine
+curl -H "Authorization: Bearer secret123" \
+  -X POST http://localhost:9000/api/task \
+  -d '{"task": "List 5 Python frameworks"}'
+```
+
+### rird export
+
+Export task history and conversation logs.
+
+```bash
+rird export [format]
+```
+
+**Formats**:
+- `json` - JSON format (default)
+- `csv` - CSV table
+- `markdown` - Markdown document
+- `pdf` - PDF report
+
+**Options**:
+- `--output <path>` - Save to file
+- `--since <date>` - Export since date (e.g., "2024-01-01")
+- `--limit <count>` - Export last N tasks
+- `--filter <query>` - Filter by keyword
+
+**Examples**:
+```bash
+# Export all as JSON
+rird export json --output my-tasks.json
+
+# Export last 10 tasks as CSV
+rird export csv --limit 10 --output tasks.csv
+
+# Export since January as Markdown
+rird export markdown --since 2024-01-01 --output report.md
+```
+
+### rird import <file>
+
+Import tasks from file.
+
+```bash
+rird import my-tasks.json
+```
+
+**Supported Formats**:
+- JSON
+- CSV
+- Markdown
+
+**Options**:
+- `--format <format>` - Specify format explicitly
+- `--merge` - Merge with existing tasks (default: replace)
+- `--dry-run` - Preview import without applying
+
+**Examples**:
+```bash
+# Import JSON file
+rird import backup.json
+
+# Import CSV and merge
+rird import tasks.csv --merge
+
+# Preview import first
+rird import data.json --dry-run
+```
+
+## Environment Variables
+
+### LLM Configuration
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `ANTHROPIC_API_KEY` | Anthropic API key | None | `sk-ant-abc123` |
+| `OPENAI_API_KEY` | OpenAI API key | None | `sk-gsk-abc123` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Google API key | None | `abc123xyz` |
+| `DEEPSEEK_API_KEY` | Deepseek API key | None | `sk-abc123` |
+| `SILICONFLOW_API_KEY` | SiliconFlow API key | None | `sf-abc123` |
+
+### RIRD Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RIRD_HOME` | Installation directory | `~/.rird` |
+| `RIRD_CONFIG` | Config file path | `~/.rird/engine/config.yaml` |
+| `RIRD_ENGINE_DIR` | Engine directory | `~/.rird/engine` |
+| `RIRD_LICENSE_KEY` | License key (overrides file) | None |
+| `RIRD_API_KEY` | API key for auth | None |
+| `DEBUG` | Enable debug logging | `0` |
+| `RIRD_SKIP_AUTO_UPDATE` | Skip auto-updates | `0` |
+
+### Execution Options
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RIRD_HEADLESS` | Browser headless mode | `true` |
+| `RIRD_TIMEOUT` | Task timeout (ms) | `30000` |
+| `RIRD_RETRIES` | Max retry attempts | `3` |
+| `RIRD_PROXY` | HTTP proxy URL | None |
+
+## Environment Variable Examples
+
+```bash
+# Use custom API key
+export OPENAI_API_KEY="sk-..."
+rird "Write Python code"
+
+# Custom installation directory
+export RIRD_HOME="/opt/rird"
+rird status
+
+# Increase timeout for slow networks
+export RIRD_TIMEOUT=60000
+rird "Complex task"
+
+# Use proxy
+export RIRD_PROXY="http://proxy.company.com:8080"
+rird "Task behind corporate proxy"
+
+# Disable auto-updates in CI
+export RIRD_SKIP_AUTO_UPDATE=1
+rird batch-process-files
+
+# Enable debug for troubleshooting
+export DEBUG=1
+rird "Debug this task"
+```
+
+## Common Workflows
+
+### Batch Task Processing
+
+```bash
+#!/bin/bash
+# Process multiple tasks
+
+while read task; do
+  echo "Running: $task"
+  rird "$task" --json > result.json
+  echo "Completed"
+done < tasks.txt
+```
+
+### CI/CD Integration
+
+```yaml
+name: RIRD Task
+on: [push]
+jobs:
+  rird-task:
+    runs-on: ubuntu-latest
+    steps:
+      - run: curl -fsSL https://rird.ai/install.sh | bash
+      - run: rird activate ${{ secrets.RIRD_LICENSE_KEY }}
+      - run: rird "Run tests and analyze results" --json
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+### Automated Script Generation
+
+```bash
+# Generate script for web scraping
+rird "Create a Python script that scrapes news from Hacker News" \
+  --output scraper.py
+
+# Run the generated script
+python scraper.py
+```
+
+### Task Queuing
+
+```bash
+# Submit tasks to server
+for i in {1..10}; do
+  curl -X POST http://localhost:8765/api/task \
+    -H "Authorization: Bearer token" \
+    -d "{\"task\": \"Task $i\"}"
+done
+```
+
+## Error Messages and Solutions
+
+### License Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Invalid license key format` | Key format incorrect | Get key from rird.ai/dashboard |
+| `License expired` | Subscription expired | Renew license on rird.ai |
+| `Device fingerprint mismatch` | License on different device | Use same device or get new key |
+| `Could not reach license server` | Network error | Check internet, verify firewall |
+
+### Configuration Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Config file not found` | Missing config.yaml | Run `rird --setup` |
+| `Invalid YAML syntax` | Config file corrupted | Check indentation (2 spaces) |
+| `Unknown model` | Model not available | Check `rird models` list |
+
+### Execution Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Task timed out` | Task took too long | Increase timeout, simplify task |
+| `Memory error` | Out of memory | Increase heap: `NODE_OPTIONS=--max-old-space-size=4096 rird <task>` |
+| `Network error` | Connection failed | Check internet, try again later |
+| `Python not found` | Python 3.8+ not installed | Install Python: brew/apt-get/python.org |
+
+## Tips and Tricks
+
+### Save Time with Aliases
+
+```bash
+# ~/.bashrc or ~/.zshrc
+
+# Quick launch
+alias r='rird'
+
+# Run with no output buffering
+alias r_debug='DEBUG=1 rird'
+
+# Export results
+alias r_json='rird --json'
+```
+
+### Piping and Redirection
+
+```bash
+# Save task output to file
+rird "Generate README" > output.txt
+
+# Use output as input to another command
+rird "List 5 fruits" | grep -i apple
+
+# Pipe task output to jq for JSON processing
+rird --json "Create config" | jq '.config'
+```
+
+### Working with Config Files
+
+```bash
+# Edit config in your default editor
+$EDITOR ~/.rird/engine/config.yaml
+
+# Validate YAML
+yamllint ~/.rird/engine/config.yaml
+
+# Pretty print JSON config
+cat ~/.rird/engine/rird.json | jq '.'
+```
+
+### Performance Monitoring
+
+```bash
+# Show performance stats
+rird --stats
+
+# Monitor in real-time
+watch -n 1 'rird --stats'
+
+# Save stats over time
+for i in {1..60}; do
+  date >> stats.log
+  rird --stats >> stats.log
+  sleep 1
+done
+```
+
+## Version History and Support
+
+**Current Version**: Check with `rird --version`
+
+**Documentation**: https://rird.ai/docs
+**GitHub**: https://github.com/rird-ai/rird
+**Issues**: https://github.com/rird-ai/rird/issues
+**Discussions**: https://github.com/rird-ai/rird/discussions