diff --git a/docs/cli/advanced.md b/docs/cli/advanced.md
new file mode 100644
index 00000000..2928e29b
--- /dev/null
+++ b/docs/cli/advanced.md
@@ -0,0 +1,745 @@
+---
+sidebar_label: Advanced Usage
+description: Advanced patterns and use cases for Roo Code CLI
+keywords:
+  - CLI advanced usage
+  - automation patterns
+  - CI/CD integration
+  - scripting
+---
+
+# Advanced Usage
+
+This guide covers advanced patterns, use cases, and integration strategies for the Roo Code CLI.
+
+## CI/CD Integration
+
+### GitHub Actions
+
+Integrate Roo Code into your GitHub workflows:
+
+```yaml
+name: AI Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  ai-review:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install Roo CLI
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      
+      - name: Run AI Review
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+        run: |
+          roo ${{ github.workspace }} \
+            -y \
+            --exit-on-complete \
+            --no-tui \
+            "Review this pull request for code quality, security issues, and best practices. Focus on the changed files."
+```
+
+### GitLab CI
+
+```yaml
+ai-review:
+  stage: review
+  image: node:20
+  
+  before_script:
+    - curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+    - export PATH="$HOME/.local/bin:$PATH"
+  
+  script:
+    - |
+      roo $CI_PROJECT_DIR \
+        -y \
+        --exit-on-complete \
+        --no-tui \
+        "Review code changes for quality and security"
+  
+  only:
+    - merge_requests
+```
+
+### Jenkins Pipeline
+
+```groovy
+pipeline {
+  agent any
+  
+  environment {
+    OPENROUTER_API_KEY = credentials('openrouter-api-key')
+  }
+  
+  stages {
+    stage('Setup') {
+      steps {
+        sh 'curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh'
+      }
+    }
+    
+    stage('AI Review') {
+      steps {
+        sh '''
+          export PATH="$HOME/.local/bin:$PATH"
+          roo $WORKSPACE \
+            -y \
+            --exit-on-complete \
+            --no-tui \
+            "Analyze code quality and suggest improvements"
+        '''
+      }
+    }
+  }
+}
+```
+
+## Batch Processing
+
+### Multiple Projects
+
+Process multiple projects with a script:
+
+```bash
+#!/bin/bash
+
+PROJECTS=(
+  ~/projects/api
+  ~/projects/frontend
+  ~/projects/mobile
+)
+
+TASK="Update README with current project structure"
+
+for project in "${PROJECTS[@]}"; do
+  echo "Processing: $project"
+  
+  if roo "$project" -y -x --no-tui "$TASK" 2>&1 | tee "$project.log"; then
+    echo "✓ Success: $project"
+  else
+    echo "✗ Failed: $project"
+  fi
+  
+  echo "---"
+done
+```
+
+### Multiple Tasks
+
+Execute multiple tasks on the same project:
+
+```bash
+#!/bin/bash
+
+PROJECT=~/my-project
+
+TASKS=(
+  "Update all dependencies to latest versions"
+  "Add JSDoc comments to public functions"
+  "Generate API documentation"
+  "Run linter and fix auto-fixable issues"
+)
+
+for task in "${TASKS[@]}"; do
+  echo "Task: $task"
+  
+  roo "$PROJECT" -y -x --no-tui "$task" 2>&1 | tee -a tasks.log
+  
+  # Wait between tasks
+  sleep 2
+done
+```
+
+## Custom Workflows
+
+### Multi-Stage Development
+
+Architect → Code → Review workflow:
+
+```bash
+#!/bin/bash
+# dev-workflow.sh
+
+PROJECT=$1
+FEATURE=$2
+
+if [ -z "$PROJECT" ] || [ -z "$FEATURE" ]; then
+  echo "Usage: $0 <project-path> <feature-description>"
+  exit 1
+fi
+
+echo "=== Stage 1: Architecture Planning ==="
+roo "$PROJECT" -M architect "Design and plan: $FEATURE"
+
+echo ""
+read -p "Proceed with implementation? (y/n) " -n 1 -r
+echo
+
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+  echo ""
+  echo "=== Stage 2: Implementation ==="
+  roo "$PROJECT" -M code "Implement the planned feature: $FEATURE"
+  
+  echo ""
+  echo "=== Stage 3: Review ==="
+  roo "$PROJECT" -M ask "Review the implementation and explain what was built"
+fi
+```
+
+Usage:
+```bash
+./dev-workflow.sh ~/my-project "user authentication with JWT"
+```
+
+### Pre-commit Hook
+
+Add AI review to git pre-commit:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Only run on changed files
+CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|js|tsx|jsx)$')
+
+if [ -z "$CHANGED_FILES" ]; then
+  exit 0
+fi
+
+echo "Running AI review on changed files..."
+
+# Create a temporary file with file list
+echo "$CHANGED_FILES" > /tmp/changed-files.txt
+
+# Run CLI review
+if roo . -y --ephemeral --no-tui "Review these changed files for issues: $(cat /tmp/changed-files.txt)" | grep -i "error\|issue\|problem"; then
+  echo ""
+  echo "⚠️  AI detected potential issues. Review the output above."
+  echo "Commit anyway? (y/n)"
+  read -r response
+  if [[ ! $response =~ ^[Yy]$ ]]; then
+    exit 1
+  fi
+fi
+
+rm /tmp/changed-files.txt
+exit 0
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+## Automation Patterns
+
+### Scheduled Tasks
+
+Use cron for scheduled CLI tasks:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add daily documentation update at 2 AM
+0 2 * * * cd ~/my-project && $HOME/.local/bin/roo . -y -x --no-tui "Update documentation to reflect latest code changes" >> ~/roo-cron.log 2>&1
+
+# Add weekly dependency check on Mondays at 9 AM
+0 9 * * 1 cd ~/my-project && $HOME/.local/bin/roo . -y -x --no-tui "Check for outdated dependencies and suggest updates" >> ~/roo-deps.log 2>&1
+```
+
+### Watch and React
+
+Monitor files and trigger CLI on changes:
+
+```bash
+#!/bin/bash
+# watch-and-review.sh
+
+PROJECT=$1
+
+if [ -z "$PROJECT" ]; then
+  echo "Usage: $0 <project-path>"
+  exit 1
+fi
+
+echo "Watching $PROJECT for changes..."
+
+# Requires fswatch: brew install fswatch (macOS) or apt-get install fswatch (Linux)
+fswatch -o "$PROJECT/src" | while read; do
+  echo "Changes detected, running review..."
+  
+  roo "$PROJECT" \
+    -y \
+    --ephemeral \
+    --no-tui \
+    "Review recent changes for code quality issues" \
+    >> "$PROJECT/watch.log" 2>&1
+  
+  echo "Review complete at $(date)"
+done
+```
+
+### Conditional Execution
+
+Execute based on conditions:
+
+```bash
+#!/bin/bash
+# conditional-review.sh
+
+PROJECT=$1
+
+# Check if tests are passing
+if npm test --prefix "$PROJECT"; then
+  echo "Tests passing, running optimization review..."
+  
+  roo "$PROJECT" -y -x --no-tui "Analyze code for optimization opportunities"
+else
+  echo "Tests failing, running debug analysis..."
+  
+  roo "$PROJECT" -M debug "Analyze test failures and suggest fixes"
+fi
+```
+
+## Integration Examples
+
+### Slack Notifications
+
+Send CLI results to Slack:
+
+```bash
+#!/bin/bash
+# roo-with-slack.sh
+
+PROJECT=$1
+TASK=$2
+SLACK_WEBHOOK=$3
+
+# Run CLI and capture output
+OUTPUT=$(roo "$PROJECT" -y -x --no-tui "$TASK" 2>&1)
+EXIT_CODE=$?
+
+# Format for Slack
+if [ $EXIT_CODE -eq 0 ]; then
+  STATUS="✅ Success"
+  COLOR="good"
+else
+  STATUS="❌ Failed"
+  COLOR="danger"
+fi
+
+# Send to Slack
+curl -X POST "$SLACK_WEBHOOK" \
+  -H 'Content-Type: application/json' \
+  -d "{
+    \"attachments\": [{
+      \"color\": \"$COLOR\",
+      \"title\": \"Roo CLI Task: $TASK\",
+      \"text\": \"$STATUS\",
+      \"fields\": [{
+        \"title\": \"Project\",
+        \"value\": \"$PROJECT\",
+        \"short\": true
+      }]
+    }]
+  }"
+```
+
+### Email Reports
+
+Email CLI output:
+
+```bash
+#!/bin/bash
+# roo-with-email.sh
+
+PROJECT=$1
+TASK=$2
+EMAIL=$3
+
+# Run CLI
+OUTPUT=$(roo "$PROJECT" -y -x --no-tui "$TASK" 2>&1)
+
+# Send email (requires mailx or similar)
+echo "$OUTPUT" | mail -s "Roo CLI Report: $TASK" "$EMAIL"
+```
+
+### Database Logging
+
+Log CLI execution to database:
+
+```bash
+#!/bin/bash
+# roo-with-db.sh
+
+PROJECT=$1
+TASK=$2
+
+START_TIME=$(date +%s)
+
+# Run CLI
+OUTPUT=$(roo "$PROJECT" -y -x --no-tui "$TASK" 2>&1)
+EXIT_CODE=$?
+
+END_TIME=$(date +%s)
+DURATION=$((END_TIME - START_TIME))
+
+# Log to database (example using PostgreSQL)
+psql -U user -d mydb -c "
+  INSERT INTO cli_logs (project, task, exit_code, duration, output, created_at)
+  VALUES ('$PROJECT', '$TASK', $EXIT_CODE, $DURATION, '$OUTPUT', NOW())
+"
+```
+
+## Performance Optimization
+
+### Parallel Execution
+
+Run multiple CLI instances in parallel:
+
+```bash
+#!/bin/bash
+# parallel-tasks.sh
+
+PROJECT=$1
+
+# Define tasks
+declare -a TASKS=(
+  "Update documentation"
+  "Run linter"
+  "Check for security issues"
+  "Analyze code complexity"
+)
+
+# Run in parallel
+for task in "${TASKS[@]}"; do
+  (
+    echo "Starting: $task"
+    roo "$PROJECT" -y -x --no-tui "$task" > "${task// /_}.log" 2>&1
+    echo "Completed: $task"
+  ) &
+done
+
+# Wait for all to complete
+wait
+
+echo "All tasks completed"
+```
+
+### Caching Strategies
+
+Cache AI responses for repeated prompts:
+
+```bash
+#!/bin/bash
+# roo-with-cache.sh
+
+PROJECT=$1
+TASK=$2
+CACHE_DIR=~/.cache/roo
+
+mkdir -p "$CACHE_DIR"
+
+# Generate cache key
+CACHE_KEY=$(echo "$PROJECT:$TASK" | md5sum | cut -d' ' -f1)
+CACHE_FILE="$CACHE_DIR/$CACHE_KEY"
+
+# Check cache
+if [ -f "$CACHE_FILE" ]; then
+  AGE=$(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE")))
+  
+  # Use cache if less than 1 hour old
+  if [ $AGE -lt 3600 ]; then
+    echo "Using cached result..."
+    cat "$CACHE_FILE"
+    exit 0
+  fi
+fi
+
+# Run CLI and cache result
+roo "$PROJECT" -y -x --no-tui "$TASK" | tee "$CACHE_FILE"
+```
+
+## Error Handling
+
+### Retry Logic
+
+Retry failed CLI executions:
+
+```bash
+#!/bin/bash
+# roo-with-retry.sh
+
+PROJECT=$1
+TASK=$2
+MAX_RETRIES=3
+RETRY_DELAY=5
+
+for i in $(seq 1 $MAX_RETRIES); do
+  echo "Attempt $i of $MAX_RETRIES"
+  
+  if roo "$PROJECT" -y -x --no-tui "$TASK"; then
+    echo "Success on attempt $i"
+    exit 0
+  else
+    echo "Failed attempt $i"
+    
+    if [ $i -lt $MAX_RETRIES ]; then
+      echo "Retrying in ${RETRY_DELAY}s..."
+      sleep $RETRY_DELAY
+    fi
+  fi
+done
+
+echo "Failed after $MAX_RETRIES attempts"
+exit 1
+```
+
+### Graceful Degradation
+
+Fallback to simpler models on failure:
+
+```bash
+#!/bin/bash
+# roo-with-fallback.sh
+
+PROJECT=$1
+TASK=$2
+
+# Try primary model
+if roo "$PROJECT" -p anthropic -m claude-sonnet-4.5 -y -x --no-tui "$TASK"; then
+  exit 0
+fi
+
+echo "Primary model failed, trying fallback..."
+
+# Fallback to different model
+if roo "$PROJECT" -p openrouter -m anthropic/claude-sonnet-4.5 -y -x --no-tui "$TASK"; then
+  exit 0
+fi
+
+echo "All models failed"
+exit 1
+```
+
+### Validation and Testing
+
+Test CLI tasks before production use:
+
+```bash
+#!/bin/bash
+# test-cli-task.sh
+
+PROJECT=$1
+TASK=$2
+
+# Create a test copy
+TEST_DIR=$(mktemp -d)
+cp -r "$PROJECT" "$TEST_DIR/project"
+
+echo "Testing in: $TEST_DIR/project"
+
+# Run CLI on test copy
+if roo "$TEST_DIR/project" -y -x --no-tui "$TASK"; then
+  echo "✓ Task succeeded on test copy"
+  
+  echo "Apply to real project? (y/n)"
+  read -r response
+  
+  if [[ $response =~ ^[Yy]$ ]]; then
+    roo "$PROJECT" -y -x "$TASK"
+  fi
+else
+  echo "✗ Task failed on test copy"
+fi
+
+# Cleanup
+rm -rf "$TEST_DIR"
+```
+
+## Security Best Practices
+
+### Secrets Management
+
+Use environment files for secrets:
+
+```bash
+#!/bin/bash
+# Load secrets from .env file
+if [ -f ~/.roo.env ]; then
+  export $(cat ~/.roo.env | xargs)
+fi
+
+# Run CLI without exposing keys in command
+roo "$PROJECT" -y -x --no-tui "$TASK"
+```
+
+Example `~/.roo.env`:
+```bash
+OPENROUTER_API_KEY=sk-or-v1-...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Protect the file:
+```bash
+chmod 600 ~/.roo.env
+```
+
+### Audit Logging
+
+Log all CLI executions:
+
+```bash
+#!/bin/bash
+# roo-audit.sh
+
+PROJECT=$1
+TASK=$2
+LOG_FILE=~/.roo-audit.log
+
+# Log execution
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | User: $(whoami) | Project: $PROJECT | Task: $TASK" >> "$LOG_FILE"
+
+# Run CLI
+roo "$PROJECT" "$@"
+
+# Log completion
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | Completed | Exit code: $?" >> "$LOG_FILE"
+```
+
+### Sandboxed Execution
+
+Run CLI in isolated environment:
+
+```bash
+#!/bin/bash
+# roo-sandbox.sh
+
+PROJECT=$1
+TASK=$2
+
+# Create isolated environment
+SANDBOX=$(mktemp -d)
+
+# Copy project to sandbox
+cp -r "$PROJECT" "$SANDBOX/project"
+
+# Run in sandbox
+roo "$SANDBOX/project" -y -x --no-tui "$TASK"
+
+# Review changes before applying
+echo "Review sandbox changes in: $SANDBOX/project"
+echo "Apply changes? (y/n)"
+read -r response
+
+if [[ $response =~ ^[Yy]$ ]]; then
+  rsync -av --delete "$SANDBOX/project/" "$PROJECT/"
+fi
+
+# Cleanup
+rm -rf "$SANDBOX"
+```
+
+## Monitoring and Observability
+
+### Metrics Collection
+
+Track CLI performance metrics:
+
+```bash
+#!/bin/bash
+# roo-metrics.sh
+
+PROJECT=$1
+TASK=$2
+
+START=$(date +%s)
+START_MEM=$(ps -o rss= -p $$ 2>/dev/null || echo 0)
+
+# Run CLI
+OUTPUT=$(roo "$PROJECT" -y -x --no-tui "$TASK" 2>&1)
+EXIT_CODE=$?
+
+END=$(date +%s)
+DURATION=$((END - START))
+END_MEM=$(ps -o rss= -p $$ 2>/dev/null || echo 0)
+MEM_USED=$((END_MEM - START_MEM))
+
+# Log metrics (could send to monitoring system)
+echo "{
+  \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
+  \"project\": \"$PROJECT\",
+  \"task\": \"$TASK\",
+  \"duration_seconds\": $DURATION,
+  \"memory_kb\": $MEM_USED,
+  \"exit_code\": $EXIT_CODE
+}" >> ~/.roo-metrics.jsonl
+```
+
+## Troubleshooting Advanced Setups
+
+### Debug Mode in Scripts
+
+Enable comprehensive debugging:
+
+```bash
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, pipe failures
+set -x             # Print commands before executing
+
+export ROO_DEBUG=1
+
+roo "$PROJECT" --debug -y -x --no-tui "$TASK" 2>&1 | tee debug.log
+```
+
+### Logging Everything
+
+Capture complete execution logs:
+
+```bash
+#!/bin/bash
+# roo-full-log.sh
+
+LOG_DIR=~/.roo-logs
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+LOG_FILE="$LOG_DIR/roo_${TIMESTAMP}.log"
+
+{
+  echo "=== Execution Start: $(date) ==="
+  echo "Project: $1"
+  echo "Task: $2"
+  echo "Environment:"
+  env | grep -E 'ROO|ANTHROPIC|OPENAI|OPENROUTER' || true
+  echo "==="
+  
+  roo "$1" -y -x --debug --no-tui "$2"
+  
+  echo "=== Execution End: $(date) ==="
+  echo "Exit Code: $?"
+} 2>&1 | tee "$LOG_FILE"
+```
+
+## Next Steps
+
+- Review the [CLI Reference](/cli/reference) for complete command documentation
+- Check the [Configuration Guide](/cli/configuration) for customization options
+- Join the [Discord community](https://discord.gg/roocode) to share your advanced use cases
diff --git a/docs/cli/authentication.md b/docs/cli/authentication.md
new file mode 100644
index 00000000..27c64293
--- /dev/null
+++ b/docs/cli/authentication.md
@@ -0,0 +1,245 @@
+---
+sidebar_label: Authentication
+description: Authenticate Roo Code CLI with Roo Code Cloud or configure your own API keys
+keywords:
+  - Roo Code CLI authentication
+  - API key setup
+  - Roo Code Cloud login
+  - CLI credentials
+---
+
+# Authentication
+
+The Roo Code CLI supports two authentication methods: Roo Code Cloud authentication for seamless provider access, or bring-your-own-key (BYOK) with direct API provider credentials.
+
+## Roo Code Cloud Authentication
+
+Roo Code Cloud provides a managed authentication service that gives you access to AI providers without managing API keys yourself.
+
+### Login
+
+To authenticate with Roo Code Cloud:
+
+```bash
+roo auth login
+```
+
+This command will:
+1. Open your default web browser to the Roo Code Cloud authentication page
+2. Wait for you to complete authentication in the browser
+3. Receive a secure token via localhost callback
+4. Store the token in `~/.config/roo/credentials.json`
+
+The authentication flow looks like this:
+
+```
+┌──────┐         ┌─────────┐         ┌───────────────┐
+│  CLI │         │ Browser │         │ Roo Code Cloud│
+└──┬───┘         └────┬────┘         └───────┬───────┘
+   │                  │                      │
+   │ Open auth URL    │                      │
+   │─────────────────>│                      │
+   │                  │                      │
+   │                  │ Authenticate         │
+   │                  │─────────────────────>│
+   │                  │                      │
+   │                  │<─────────────────────│
+   │                  │ Token via callback   │
+   │<─────────────────│                      │
+   │                  │                      │
+   │ Store token      │                      │
+   │                  │                      │
+```
+
+:::info Token Validity
+Authentication tokens are valid for 90 days. The CLI will prompt you to re-authenticate when your token expires.
+:::
+
+### Check Status
+
+To verify your authentication status:
+
+```bash
+roo auth status
+```
+
+This displays:
+- Whether you're authenticated
+- Token expiration date (if authenticated)
+- Associated account information
+
+Example output:
+```
+✓ Authenticated with Roo Code Cloud
+  Token expires: 2026-04-23
+  Account: user@example.com
+```
+
+### Logout
+
+To remove your stored authentication token:
+
+```bash
+roo auth logout
+```
+
+This clears the token from `~/.config/roo/credentials.json` but preserves other CLI settings.
+
+## Bring Your Own Key (BYOK)
+
+If you prefer to use your own API keys from AI providers, you can configure them directly.
+
+### Setting API Keys
+
+API keys can be provided in three ways (in order of precedence):
+
+1. **Command Line Flag**: `--api-key` or `-k`
+2. **Environment Variable**: Provider-specific variable
+3. **Prompt**: The CLI will ask for a key if none is found
+
+### Provider Environment Variables
+
+Each provider has a specific environment variable for API keys:
+
+| Provider | Environment Variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Google/Gemini | `GOOGLE_API_KEY` |
+| OpenAI Native | `OPENAI_API_KEY` |
+
+### Example: Using OpenRouter
+
+Set your API key as an environment variable:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+Then run the CLI without additional flags:
+
+```bash
+roo "Refactor the utils.ts file" -w ~/my-project
+```
+
+### Example: Using Command Line Flag
+
+Provide the API key directly in the command:
+
+```bash
+roo ~/my-project \
+  --provider anthropic \
+  --api-key sk-ant-... \
+  "Add unit tests"
+```
+
+:::warning Security Note
+Be careful when using `--api-key` in commands, as the key may be stored in your shell history. Using environment variables or credential files is more secure.
+:::
+
+## Credential Storage
+
+### Roo Code Cloud Credentials
+
+Roo Code Cloud tokens are stored in:
+```
+~/.config/roo/credentials.json
+```
+
+This file has restrictive permissions (mode 0600) to protect your credentials.
+
+### API Key Storage
+
+API keys are NOT stored by the CLI. You must:
+- Set them as environment variables
+- Provide them via command line flags
+- Let the CLI prompt you each time
+
+For convenience, add API keys to your shell profile:
+
+```bash
+# In ~/.bashrc, ~/.zshrc, or equivalent
+export OPENROUTER_API_KEY=sk-or-v1-...
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Authentication Priority
+
+When determining which credentials to use, the CLI follows this priority:
+
+1. **Command line flags** (`--api-key`, `--provider`)
+2. **Environment variables** (provider-specific)
+3. **Roo Code Cloud authentication** (if logged in)
+4. **Interactive prompt** (CLI asks for missing credentials)
+
+## Advanced Configuration
+
+### Custom Roo Code Cloud URL
+
+For enterprise or development environments, you can override the Roo Code Cloud URL:
+
+```bash
+export ROO_WEB_APP_URL=https://custom-roo-instance.example.com
+```
+
+### Proxy Configuration
+
+If you're behind a corporate proxy, set standard proxy environment variables:
+
+```bash
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+```
+
+## Troubleshooting
+
+### Browser Doesn't Open
+
+If `roo auth login` doesn't open your browser:
+
+1. Manually copy the URL displayed in the terminal
+2. Paste it into your browser
+3. Complete authentication
+4. The CLI will detect the callback automatically
+
+### Token Expired
+
+If you see token expiration errors:
+
+```bash
+roo auth login
+```
+
+This will refresh your authentication token.
+
+### Permission Denied on Credentials File
+
+If you get permission errors reading/writing credentials:
+
+```bash
+chmod 600 ~/.config/roo/credentials.json
+```
+
+### Multiple API Keys
+
+To switch between different API keys, use separate environment variable names or shell profiles:
+
+```bash
+# Development key
+export DEV_API_KEY=sk-...
+
+# Production key  
+export PROD_API_KEY=sk-...
+
+# Use specific key
+roo ~/project --api-key $DEV_API_KEY
+```
+
+## Next Steps
+
+After setting up authentication:
+
+1. [Get started with your first command](/cli/getting-started)
+2. [Learn about configuration options](/cli/configuration)
+3. [Explore interactive and non-interactive modes](/cli/usage)
diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md
new file mode 100644
index 00000000..28344409
--- /dev/null
+++ b/docs/cli/configuration.md
@@ -0,0 +1,435 @@
+---
+sidebar_label: Configuration
+description: Configure Roo Code CLI with settings files, environment variables, and command-line flags
+keywords:
+  - CLI configuration
+  - settings file
+  - CLI preferences
+  - default options
+---
+
+# Configuration
+
+The Roo Code CLI can be configured through a combination of settings files, environment variables, and command-line flags.
+
+## Configuration Priority
+
+When the CLI determines what settings to use, it follows this priority (highest to lowest):
+
+1. **Command-line flags** - Explicitly provided options
+2. **Environment variables** - Shell environment settings
+3. **Settings file** - Saved preferences in `~/.config/roo/cli-settings.json`
+4. **Defaults** - Built-in default values
+
+## Settings File
+
+The CLI stores persistent settings in a JSON file located at:
+
+```
+~/.config/roo/cli-settings.json
+```
+
+### Settings File Format
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code",
+  "reasoningEffort": "medium",
+  "dangerouslySkipPermissions": false,
+  "oneshot": false,
+  "onboardingProviderChoice": "roo"
+}
+```
+
+### Available Settings
+
+| Setting | Type | Description | Default |
+| --- | --- | --- | --- |
+| `provider` | string | Default AI provider | `openrouter` |
+| `model` | string | Default model name | `anthropic/claude-sonnet-4.5` |
+| `mode` | string | Default mode to start in | `code` |
+| `reasoningEffort` | string | Default reasoning effort level | `medium` |
+| `dangerouslySkipPermissions` | boolean | Auto-approve all actions | `false` |
+| `oneshot` | boolean | Exit after task completion | `false` |
+| `onboardingProviderChoice` | string | Provider choice from onboarding | - |
+
+### Manually Editing Settings
+
+You can edit the settings file directly:
+
+```bash
+# Open in your default editor
+$EDITOR ~/.config/roo/cli-settings.json
+
+# Or use nano
+nano ~/.config/roo/cli-settings.json
+```
+
+Example configuration for daily use:
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code",
+  "reasoningEffort": "medium"
+}
+```
+
+Example configuration for CI/CD:
+
+```json
+{
+  "provider": "openrouter",
+  "model": "anthropic/claude-sonnet-4.5",
+  "dangerouslySkipPermissions": true,
+  "oneshot": true
+}
+```
+
+### Resetting Settings
+
+To reset all settings to defaults:
+
+```bash
+rm ~/.config/roo/cli-settings.json
+```
+
+The CLI will recreate the file with default values on next run.
+
+## Environment Variables
+
+Environment variables provide a flexible way to configure the CLI without modifying files.
+
+### API Configuration
+
+```bash
+# Provider-specific API keys
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export OPENROUTER_API_KEY=sk-or-v1-...
+export GOOGLE_API_KEY=...
+
+# Roo Code Cloud
+export ROO_WEB_APP_URL=https://app.roocode.com
+```
+
+### CLI Behavior
+
+While the CLI doesn't directly use behavior environment variables, you can create shell aliases that use them:
+
+```bash
+# In your ~/.bashrc or ~/.zshrc
+export DEFAULT_ROO_PROVIDER=anthropic
+export DEFAULT_ROO_MODEL=claude-sonnet-4.5
+
+# Create an alias that uses these
+alias roo-dev='roo --provider $DEFAULT_ROO_PROVIDER --model $DEFAULT_ROO_MODEL'
+```
+
+## Command-Line Flags
+
+Command-line flags override all other configuration sources. See the [CLI Reference](/cli/reference) for a complete list.
+
+### Common Flag Examples
+
+```bash
+# Override provider
+roo "Task" -p anthropic  -w ~/project
+
+# Override model
+roo "Task" -m claude-sonnet-4.5  -w ~/project
+
+# Override mode
+roo "Task" -M architect  -w ~/project
+
+# Multiple overrides
+roo ~/project \
+  -p anthropic \
+  -m claude-sonnet-4.5 \
+  -M code \
+  -r high \
+  "Complex task"
+```
+
+## Configuration Strategies
+
+### Local Development
+
+For local development work:
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code",
+  "reasoningEffort": "medium"
+}
+```
+
+Use interactively to review changes before applying.
+
+### Automation & Scripts
+
+For automated tasks and CI/CD:
+
+```json
+{
+  "provider": "openrouter",
+  "dangerouslySkipPermissions": true,
+  "oneshot": true
+}
+```
+
+Always use the `-y` flag in scripts:
+
+```bash
+roo ~/project -y "Generate tests"
+```
+
+### Multiple Configurations
+
+Manage different configurations with shell profiles or scripts:
+
+```bash
+#!/bin/bash
+# dev-config.sh
+export ANTHROPIC_API_KEY=sk-ant-dev-...
+alias roo='command roo --provider anthropic --mode code'
+```
+
+```bash
+#!/bin/bash
+# ci-config.sh  
+export OPENROUTER_API_KEY=sk-or-ci-...
+alias roo='command roo --provider openrouter -y --exit-on-complete'
+```
+
+Source the appropriate config:
+
+```bash
+source dev-config.sh
+roo "Task" -w ~/project
+```
+
+### Per-Project Configuration
+
+Create project-specific wrapper scripts:
+
+```bash
+#!/bin/bash
+# ~/my-project/roo.sh
+
+# Project-specific settings
+PROVIDER="anthropic"
+MODEL="claude-sonnet-4.5"
+MODE="code"
+
+# Run CLI with project settings
+roo "$(dirname "$0")" \
+  --provider "$PROVIDER" \
+  --model "$MODEL" \
+  --mode "$MODE" \
+  "$@"
+```
+
+Usage:
+
+```bash
+cd ~/my-project
+./roo.sh "Add tests"
+```
+
+## Debugging Configuration
+
+To see what configuration the CLI is using, run with the `--debug` flag:
+
+```bash
+roo ~/project --debug "Test"
+```
+
+This will show:
+- Which settings file was loaded
+- Environment variables detected
+- Final resolved configuration
+- Provider and model information
+
+## Security Considerations
+
+### File Permissions
+
+The CLI automatically sets secure permissions on sensitive files:
+
+- **Settings file**: `~/.config/roo/cli-settings.json` (mode 0644)
+- **Credentials file**: `~/.config/roo/credentials.json` (mode 0600)
+
+### API Key Storage
+
+**Never store API keys in the settings file.** Always use:
+
+1. Environment variables (recommended)
+2. Command-line flags (for one-off uses)
+3. Roo Code Cloud authentication (most secure)
+
+### Dangerous Flags
+
+The `dangerouslySkipPermissions` setting is dangerous because it auto-approves all actions:
+
+- File writes without review
+- Command execution without confirmation
+- Potentially destructive operations
+
+Only use this in controlled environments like CI/CD where you trust the prompts being executed.
+
+## Advanced Configuration
+
+### Custom Extension Path
+
+Specify a custom extension bundle location:
+
+```bash
+roo ~/project --extension /path/to/custom/extension "Task"
+```
+
+Useful for:
+- Testing extension changes
+- Using a specific extension version
+- Development and debugging
+
+### Ephemeral Mode
+
+Run without persisting any state:
+
+```bash
+roo ~/project --ephemeral "Quick analysis"
+```
+
+In ephemeral mode:
+- No task history is saved
+- Settings changes aren't persisted
+- Temporary storage is used
+- Useful for one-off commands
+
+### Disabling TUI
+
+For plain text output (useful for logging):
+
+```bash
+roo ~/project --no-tui "Task"
+```
+
+Output can be piped or redirected:
+
+```bash
+roo ~/project --no-tui -y "Analyze" > output.txt
+```
+
+## Configuration Examples
+
+### Example 1: Personal Development
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code",
+  "reasoningEffort": "medium"
+}
+```
+
+```bash
+# In ~/.bashrc
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Example 2: Team Environment
+
+```json
+{
+  "provider": "openrouter",
+  "model": "anthropic/claude-sonnet-4.5"
+}
+```
+
+```bash
+# Shared in team documentation
+export OPENROUTER_API_KEY=sk-or-team-...
+
+# Team members use same config
+roo "Task" -w ~/project
+```
+
+### Example 3: CI/CD Pipeline
+
+```json
+{
+  "provider": "openrouter",
+  "dangerouslySkipPermissions": true,
+  "oneshot": true
+}
+```
+
+```yaml
+# .github/workflows/ai-review.yml
+- name: AI Code Review
+  env:
+    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+  run: |
+    roo ${{ github.workspace }} \
+      -y \
+      --exit-on-complete \
+      --no-tui \
+      "Review changes in this PR"
+```
+
+## Troubleshooting
+
+### Settings Not Applied
+
+If your settings aren't being used:
+
+1. Check file location: `ls -la ~/.config/roo/cli-settings.json`
+2. Verify JSON syntax: `cat ~/.config/roo/cli-settings.json | jq`
+3. Check file permissions: `ls -la ~/.config/roo/`
+4. Look for override flags in your command
+5. Enable debug mode: `--debug`
+
+### Invalid Configuration
+
+If the CLI reports invalid configuration:
+
+```bash
+# Backup current settings
+cp ~/.config/roo/cli-settings.json ~/.config/roo/cli-settings.json.bak
+
+# Remove and let CLI recreate with defaults
+rm ~/.config/roo/cli-settings.json
+
+# Run CLI - it will create new settings file
+roo --help
+```
+
+### Permission Errors
+
+If you can't write to the config directory:
+
+```bash
+# Check permissions
+ls -la ~/.config/
+
+# Create directory if needed
+mkdir -p ~/.config/roo
+chmod 700 ~/.config/roo
+
+# Reset file permissions
+chmod 644 ~/.config/roo/cli-settings.json
+chmod 600 ~/.config/roo/credentials.json
+```
+
+## Next Steps
+
+- [Review the complete CLI reference](/cli/reference) for all available options
+- [Learn about interactive and non-interactive usage](/cli/usage)
+- [Explore advanced use cases and patterns](/cli/advanced)
diff --git a/docs/cli/getting-started.md b/docs/cli/getting-started.md
new file mode 100644
index 00000000..a1b2ba46
--- /dev/null
+++ b/docs/cli/getting-started.md
@@ -0,0 +1,334 @@
+---
+sidebar_label: Getting Started
+description: Learn how to use Roo Code CLI with your first commands and examples
+keywords:
+  - Roo Code CLI tutorial
+  - CLI getting started
+  - first CLI command
+  - terminal workflow
+---
+
+# Getting Started with Roo Code CLI
+
+This guide will walk you through running your first Roo Code CLI commands and understanding the basics.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+1. [Installed the Roo Code CLI](/cli/installation)
+2. [Set up authentication](/cli/authentication) (Roo Code Cloud or API key)
+
+## Your First Command
+
+The simplest way to run the CLI is with a prompt and optional workspace:
+
+```bash
+roo "What is this project?" -w ~/my-project
+```
+
+Or if you're already in the project directory:
+
+```bash
+cd ~/my-project
+roo "What is this project?"
+```
+
+This command:
+- Executes the prompt "What is this project?"
+- Uses `~/my-project` as the workspace (or current directory if `-w` is omitted)
+- Starts in interactive mode with a terminal UI
+- Waits for your approval before executing any actions
+
+### Understanding the Output
+
+When you run the command, you'll see:
+
+1. **Initialization**: CLI loads the extension and connects to the AI provider
+2. **Task Execution**: The AI analyzes your prompt and proposes actions
+3. **Tool Approvals**: You're prompted to approve file reads, commands, etc.
+4. **Results**: The AI presents its findings and awaits your response
+
+## Interactive Mode
+
+By default, the CLI runs in interactive mode with a rich terminal UI.
+
+### Starting Interactive Mode
+
+Run without a prompt to enter interactive mode:
+
+```bash
+roo ~/my-project
+```
+
+You'll be presented with an input prompt where you can:
+- Type your task or question
+- Use tab completion for files and commands
+- Access command history with up/down arrows
+- Enter multi-line prompts with Shift+Enter
+
+### Approving Actions
+
+In interactive mode, the CLI will prompt for approval before:
+
+- **Reading files**: "Allow reading file: src/utils.ts?"
+- **Writing files**: "Allow writing to: src/config.ts?"
+- **Running commands**: "Execute command: npm test?"
+- **Browser actions**: "Open browser to: https://example.com?"
+- **MCP tool usage**: "Use MCP tool: database_query?"
+
+Respond with:
+- `y` or `yes` to approve
+- `n` or `no` to reject
+- `a` or `always` to approve all future actions of this type
+
+## Non-Interactive Mode
+
+For automation and scripts, use non-interactive mode with the `-y` flag:
+
+```bash
+roo ~/my-project -y "Add JSDoc comments to all functions"
+```
+
+In non-interactive mode:
+- All actions are auto-approved
+- No user input is required
+- Follow-up questions show a 60-second timeout
+- The CLI exits when the task completes
+
+:::warning
+Use non-interactive mode carefully, as it will execute all proposed actions without confirmation.
+:::
+
+## Common Workflows
+
+### Code Analysis
+
+Analyze code without making changes:
+
+```bash
+roo "Analyze the architecture and suggest improvements" -w ~/my-project
+```
+
+### Refactoring
+
+Refactor code with approval for each change:
+
+```bash
+roo "Refactor src/utils.ts to use modern ES6 syntax" -w ~/my-project
+```
+
+### Documentation Generation
+
+Generate documentation automatically:
+
+```bash
+roo ~/my-project -y "Generate API documentation in docs/api.md"
+```
+
+### Test Creation
+
+Create tests interactively:
+
+```bash
+roo "Create unit tests for src/auth.ts" -w ~/my-project
+```
+
+### Bug Investigation
+
+Debug issues with full context:
+
+```bash
+roo "Why is the login form not submitting?" -w ~/my-project
+```
+
+## Working with Files
+
+### Specify Files in Prompts
+
+Reference specific files in your prompts:
+
+```bash
+roo "Review src/auth.ts and src/api.ts for security issues" -w ~/my-project
+```
+
+### Reading from Files
+
+You can load prompts from files:
+
+```bash
+echo "Analyze the codebase and create a README" > task.txt
+roo "$(cat task.txt)" -w ~/my-project
+```
+
+Or use stdin:
+
+```bash
+echo "Add error handling" | roo ~/my-project
+```
+
+## Using Different Providers and Models
+
+### Specify Provider
+
+Choose your AI provider:
+
+```bash
+roo "Explain this code" -p anthropic  -w ~/my-project
+```
+
+Supported providers:
+- `anthropic` - Claude models
+- `openai-native` - OpenAI models
+- `openrouter` - OpenRouter (default)
+- `gemini` - Google Gemini
+- `roo` - Roo Code Cloud
+
+### Specify Model
+
+Use a specific model:
+
+```bash
+roo ~/my-project \
+  -p anthropic \
+  -m claude-sonnet-4.5 \
+  "Optimize this database query"
+```
+
+### Use Different Modes
+
+Start in a specific mode:
+
+```bash
+roo "Design a new user authentication system" -M architect  -w ~/my-project
+```
+
+Available modes:
+- `code` - Code implementation (default)
+- `architect` - Planning and design
+- `ask` - Questions and explanations
+- `debug` - Debugging and troubleshooting
+
+## Advanced Examples
+
+### Multi-Step Task
+
+Let the AI work through a complex task:
+
+```bash
+roo "Create a new API endpoint for user registration including route, controller, validation, and tests" -w ~/my-project
+```
+
+### With Reasoning Effort
+
+Adjust reasoning effort for complex problems:
+
+```bash
+roo ~/my-project \
+  -r high \
+  "Optimize this algorithm for better time complexity"
+```
+
+Reasoning levels: `none`, `minimal`, `low`, `medium` (default), `high`, `xhigh`
+
+### Exit on Completion
+
+Automatically exit when the task is done:
+
+```bash
+roo ~/my-project \
+  --exit-on-complete \
+  -y \
+  "Format all TypeScript files"
+```
+
+### Ephemeral Mode
+
+Run without saving history or state:
+
+```bash
+roo ~/my-project --ephemeral "Quick code review"
+```
+
+## Tips for Success
+
+### 1. Be Specific
+
+Good prompt:
+```bash
+roo "Add input validation to the signup form in src/components/SignupForm.tsx using Zod" -w ~/my-project
+```
+
+Vague prompt:
+```bash
+roo "Fix the form" -w ~/my-project
+```
+
+### 2. Provide Context
+
+Include relevant information in your prompt:
+```bash
+roo "The API returns 500 errors when creating users. Check the error logs in logs/error.log and fix the issue in src/api/users.ts" -w ~/my-project
+```
+
+### 3. Use Modes Appropriately
+
+- **Architect mode** for planning: Design before implementing
+- **Code mode** for implementation: Write and modify code
+- **Ask mode** for understanding: Learn about the codebase
+- **Debug mode** for troubleshooting: Investigate and fix issues
+
+### 4. Review Before Approving
+
+In interactive mode, carefully review proposed changes before approving file writes or potentially destructive commands.
+
+### 5. Start Simple
+
+Begin with read-only analysis tasks to understand how the CLI works before having it make changes.
+
+## Keyboard Shortcuts
+
+In the interactive TUI:
+
+- `Ctrl+C` - Cancel current operation
+- `Ctrl+D` - Exit the CLI
+- `Tab` - Autocomplete files and commands
+- `↑/↓` - Navigate command history
+- `Shift+Enter` - New line in input (for multi-line prompts)
+- `Enter` - Submit prompt
+
+## Next Steps
+
+Now that you understand the basics:
+
+1. [Learn about configuration](/cli/configuration) to customize default settings
+2. [Explore usage patterns](/cli/usage) for interactive and non-interactive modes
+3. [Review CLI reference](/cli/reference) for all available options and commands
+
+## Troubleshooting
+
+### CLI Hangs
+
+If the CLI appears stuck:
+- Press `Ctrl+C` to cancel
+- Check your internet connection
+- Verify API key or authentication is valid
+- Look for errors with `--debug` flag
+
+### Unexpected Behavior
+
+Enable debug output to see what's happening:
+
+```bash
+roo ~/my-project --debug "Your prompt"
+```
+
+### Commands Not Working
+
+Verify the CLI is using the correct workspace:
+
+```bash
+roo "List files in the current directory" -w ~/my-project
+```
+
+The CLI should show files from `~/my-project`, not your current terminal directory.
diff --git a/docs/cli/installation.md b/docs/cli/installation.md
new file mode 100644
index 00000000..f6aba917
--- /dev/null
+++ b/docs/cli/installation.md
@@ -0,0 +1,179 @@
+---
+sidebar_label: Installation
+description: Install Roo Code CLI on macOS and Linux with our one-command installer
+keywords:
+  - Roo Code CLI installation
+  - install CLI
+  - terminal setup
+  - command line tools
+---
+
+# Installing Roo Code CLI
+
+The Roo Code CLI can be installed with a single command on macOS and Linux systems.
+
+## Requirements
+
+Before installing, ensure you have:
+
+- **Node.js 20 or higher** - Check with `node --version`
+- **Operating System**: macOS (Intel or Apple Silicon) or Linux (x64 or ARM64)
+- **Terminal Access**: Command line access with curl installed
+
+## Quick Install (Recommended)
+
+Install the Roo Code CLI with a single command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+```
+
+This script will:
+1. Detect your operating system and architecture
+2. Download the appropriate CLI bundle
+3. Install it to `~/.roo/cli`
+4. Create a symlink in `~/.local/bin/roo`
+5. Make the CLI executable
+
+After installation completes, verify it worked:
+
+```bash
+roo --version
+```
+
+:::tip
+If the `roo` command isn't found, make sure `~/.local/bin` is in your PATH. Add this to your shell profile:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+:::
+
+## Custom Installation Directory
+
+You can customize where the CLI is installed using environment variables:
+
+```bash
+ROO_INSTALL_DIR=/opt/roo-code ROO_BIN_DIR=/usr/local/bin \
+  curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+```
+
+- `ROO_INSTALL_DIR`: Where the CLI bundle is extracted (default: `~/.roo/cli`)
+- `ROO_BIN_DIR`: Where the `roo` symlink is created (default: `~/.local/bin`)
+
+## Installing a Specific Version
+
+To install a specific version of the CLI:
+
+```bash
+ROO_VERSION=0.0.49 curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+```
+
+Replace `0.0.49` with your desired version number. See [available releases](https://github.com/RooCodeInc/Roo-Code/releases) on GitHub.
+
+## Updating
+
+To update to the latest version, simply re-run the install script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
+```
+
+The script will download and install the latest version, replacing your existing installation.
+
+## Uninstalling
+
+To completely remove the Roo Code CLI:
+
+```bash
+rm -rf ~/.roo/cli ~/.local/bin/roo
+```
+
+If you used custom directories, adjust the paths accordingly.
+
+:::info
+This only removes the CLI itself. If you also want to remove stored settings and credentials:
+
+```bash
+rm -rf ~/.config/roo
+```
+:::
+
+## Development Installation
+
+If you want to contribute to the CLI or build from source:
+
+### Prerequisites
+
+- Node.js 20 or higher
+- pnpm package manager
+- Git
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/RooCodeInc/Roo-Code.git
+cd Roo-Code
+
+# Install dependencies
+pnpm install
+
+# Build the main extension first
+pnpm --filter roo-cline bundle
+
+# Build the CLI
+pnpm --filter @roo-code/cli build
+
+# Run directly (without installing)
+cd apps/cli
+node dist/index.js --help
+```
+
+For more details on local development, see the [CLI README](https://github.com/RooCodeInc/Roo-Code/blob/main/apps/cli/README.md).
+
+## Troubleshooting
+
+### Command Not Found
+
+If you get `command not found: roo` after installation:
+
+1. Check that the symlink was created: `ls -la ~/.local/bin/roo`
+2. Verify `~/.local/bin` is in your PATH: `echo $PATH`
+3. Add to PATH if needed: `export PATH="$HOME/.local/bin:$PATH"`
+4. Restart your terminal
+
+### Permission Denied
+
+If you encounter permission errors during installation:
+
+1. Try without sudo first (the script installs to your home directory)
+2. Check file permissions: `ls -la ~/.roo/cli`
+3. Ensure you have write access to the installation directory
+
+### Download Fails
+
+If the download fails:
+
+1. Check your internet connection
+2. Verify curl is installed: `curl --version`
+3. Try downloading manually from [GitHub Releases](https://github.com/RooCodeInc/Roo-Code/releases)
+4. Check if GitHub is accessible from your network
+
+### Architecture Not Supported
+
+The CLI currently supports:
+- macOS Intel (x64)
+- macOS Apple Silicon (arm64)
+- Linux x64
+- Linux arm64
+
+If your system isn't supported, you can try [building from source](#development-installation).
+
+## Next Steps
+
+Now that the CLI is installed:
+
+1. [Configure authentication](/cli/authentication) to use Roo Code Cloud or set up your API key
+2. [Follow the getting started guide](/cli/getting-started) to run your first command
+3. [Learn about configuration options](/cli/configuration) to customize your setup
diff --git a/docs/cli/overview.md b/docs/cli/overview.md
new file mode 100644
index 00000000..273d327e
--- /dev/null
+++ b/docs/cli/overview.md
@@ -0,0 +1,67 @@
+---
+sidebar_label: CLI Overview
+description: Introduction to Roo Code CLI - Run the Roo Code agent from your terminal without VSCode
+keywords:
+  - Roo Code CLI
+  - command line interface
+  - terminal AI assistant
+  - headless automation
+---
+
+# Roo Code CLI Overview
+
+The Roo Code CLI allows you to run the Roo Code agent directly from your terminal without needing VSCode. It provides a powerful command-line interface for AI-powered coding assistance, perfect for automation, CI/CD pipelines, and terminal-based workflows.
+
+## What is the Roo Code CLI?
+
+The Roo Code CLI is a standalone command-line tool that brings all the power of the Roo Code VSCode extension to your terminal. It uses a VSCode API compatibility layer (`@roo-code/vscode-shim`) to run the full Roo Code extension in a Node.js environment.
+
+## Key Features
+
+- **Interactive TUI Mode**: Rich terminal user interface with real-time updates and interactive prompts
+- **Non-Interactive Mode**: Fully automated execution for scripts and CI/CD pipelines
+- **All Roo Code Features**: Access to modes, tools, MCP integration, and more
+- **Roo Code Cloud Integration**: Authenticate and use Roo Code Cloud features
+- **Flexible Configuration**: Configure via CLI flags, environment variables, or settings file
+- **Cross-Platform**: Works on macOS and Linux (Intel, ARM64, and Apple Silicon)
+
+## Use Cases
+
+### Development Workflows
+Run Roo Code tasks from your terminal for quick code analysis, refactoring, or documentation generation without opening VSCode.
+
+### CI/CD Automation
+Integrate Roo Code into your continuous integration pipelines to automate code reviews, generate tests, or validate code quality.
+
+### Server Administration
+Use Roo Code on remote servers where VSCode isn't available or practical.
+
+### Scripting and Automation
+Write scripts that leverage Roo Code's AI capabilities for batch processing or automated tasks.
+
+## How It Works
+
+The CLI wraps the Roo Code extension with a VSCode API shim:
+
+1. **CLI Entry Point** parses command line arguments and initializes the extension host
+2. **Extension Host** creates a VSCode API mock and loads the extension bundle
+3. **Message Flow** enables bidirectional communication between CLI and extension
+4. **Terminal UI** renders the interactive interface or plain text output
+
+## Requirements
+
+- Node.js 20 or higher
+- macOS (Intel or Apple Silicon) or Linux (x64 or ARM64)
+- An API key for your chosen AI provider (or Roo Code Cloud authentication)
+
+## Getting Started
+
+Ready to start using the Roo Code CLI? Check out the [Installation](/cli/installation) guide to get set up, then follow the [Getting Started](/cli/getting-started) guide to run your first command.
+
+## Getting Support
+
+If you encounter issues with the CLI:
+
+* Join our [Discord community](https://discord.gg/roocode) for real-time support
+* Submit issues on [GitHub](https://github.com/RooCodeInc/Roo-Code/issues)
+* Visit our [Reddit community](https://www.reddit.com/r/RooCode)
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
new file mode 100644
index 00000000..184eace3
--- /dev/null
+++ b/docs/cli/reference.md
@@ -0,0 +1,616 @@
+---
+sidebar_label: CLI Reference
+description: Complete reference for all Roo Code CLI commands, options, and flags
+keywords:
+  - CLI reference
+  - command line options
+  - CLI flags
+  - CLI commands
+---
+
+# CLI Reference
+
+Complete reference for the Roo Code CLI, including all commands, options, and flags.
+
+## Basic Syntax
+
+```bash
+roo [prompt] [options]
+```
+
+Or use authentication commands:
+
+```bash
+roo auth <command>
+```
+
+## Main Command
+
+### `roo [prompt]`
+
+Run the Roo Code agent with a prompt.
+
+**Arguments:**
+- `[prompt]` - The task or prompt to execute (positional argument, optional)
+
+**Examples:**
+```bash
+roo "Analyze the code"
+roo "Analyze the code" -w ~/my-project
+roo  # starts interactive mode without prompt
+```
+
+## Global Options
+
+### `-w, --workspace <path>`
+
+Workspace directory path to operate in.
+
+```bash
+roo "Add error handling" -w ~/project
+```
+
+**Default:** Current working directory
+
+### `-p, --provider <provider>`
+
+AI provider to use.
+
+**Supported providers:**
+- `anthropic` - Claude models from Anthropic
+- `openai-native` - OpenAI models
+- `openrouter` - OpenRouter (default)
+- `gemini` - Google Gemini models  
+- `roo` - Roo Code Cloud
+
+**Example:**
+```bash
+roo "Task" -p anthropic  -w ~/project
+```
+
+**Default:** `openrouter`
+
+### `-m, --model <model>`
+
+Model to use for the task.
+
+**Example:**
+```bash
+roo "Task" -m claude-sonnet-4.5  -w ~/project
+```
+
+**Default:** `anthropic/claude-sonnet-4.5`
+
+**Common models:**
+- `claude-sonnet-4.5` - Latest Claude Sonnet (Anthropic)
+- `claude-opus-4` - Claude Opus (Anthropic)
+- `gpt-4o` - GPT-4 Optimized (OpenAI)
+- `anthropic/claude-sonnet-4.5` - Via OpenRouter
+- `openai/gpt-4o` - Via OpenRouter
+
+### `-k, --api-key <key>`
+
+API key for the provider.
+
+```bash
+roo "Task" -k sk-ant-...  -w ~/project
+```
+
+:::warning
+Avoid using this flag when possible. API keys may be stored in shell history. Use environment variables instead.
+:::
+
+**Precedence:**
+1. `--api-key` flag
+2. Environment variable (e.g., `ANTHROPIC_API_KEY`)
+3. Roo Code Cloud authentication
+4. Interactive prompt
+
+### `-M, --mode <mode>`
+
+Mode to start in.
+
+**Available modes:**
+- `code` - Code implementation (default)
+- `architect` - Planning and design
+- `ask` - Questions and explanations
+- `debug` - Debugging and troubleshooting
+
+**Example:**
+```bash
+roo "Design a REST API" -M architect  -w ~/project
+```
+
+**Default:** `code`
+
+### `-r, --reasoning-effort <level>`
+
+Set the reasoning effort level for the AI.
+
+**Levels:**
+- `disabled` - Disable extended thinking
+- `none` - No extended thinking
+- `minimal` - Minimal thinking
+- `low` - Low effort
+- `medium` - Medium effort (default)
+- `high` - High effort
+- `xhigh` - Extra high effort (most thorough)
+- `unspecified` - Let the provider decide
+
+**Example:**
+```bash
+roo "Optimize this algorithm" -r high  -w ~/project
+```
+
+Higher reasoning effort may result in:
+- More thorough analysis
+- Better solutions to complex problems
+- Longer response times
+- Higher token usage
+
+**Default:** `medium`
+
+## Behavior Options
+
+### `-y, --yes`
+
+Non-interactive mode: auto-approve all actions.
+
+```bash
+roo ~/project -y "Format all files"
+```
+
+:::danger
+This will execute all proposed actions without confirmation. Use carefully.
+:::
+
+**What gets auto-approved:**
+- File reads and writes
+- Command executions
+- Browser actions
+- MCP tool usage
+- All other tool invocations
+
+**When to use:**
+- CI/CD pipelines
+- Trusted automation scripts
+- Batch processing
+- Well-tested workflows
+
+### `-x, --exit-on-complete`
+
+Exit the CLI when the task completes.
+
+```bash
+roo "Generate docs" -x -y  -w ~/project
+```
+
+Useful for:
+- Scripts that chain multiple operations
+- CI/CD workflows
+- Scheduled tasks
+- One-off commands
+
+**Default:** Stays open for more interaction
+
+### `--ephemeral`
+
+Run without persisting state (uses temporary storage).
+
+```bash
+roo ~/project --ephemeral "Quick analysis"
+```
+
+**What isn't saved:**
+- Task history
+- Conversation state  
+- Settings changes
+- Any other persistent data
+
+Useful for:
+- Quick one-off commands
+- Testing without polluting history
+- Privacy-sensitive tasks
+
+### `--no-tui`
+
+Disable the terminal UI, use plain text output.
+
+```bash
+roo ~/project --no-tui "Task"
+```
+
+Useful for:
+- Logging output to files
+- Piping to other commands
+- Non-interactive terminals
+- CI/CD environments
+
+**Example with output redirection:**
+```bash
+roo ~/project --no-tui -y "Task" 2>&1 | tee output.log
+```
+
+### `-d, --debug`
+
+Enable debug output.
+
+```bash
+roo ~/project --debug "Task"
+```
+
+**Debug output includes:**
+- Configuration details
+- Provider/model information
+- File paths and locations
+- Extension loading process
+- Message flow details
+- Detailed error information
+
+Useful for:
+- Troubleshooting issues
+- Understanding CLI behavior
+- Reporting bugs
+- Development
+
+## Advanced Options
+
+### `-e, --extension <path>`
+
+Path to a custom extension bundle directory.
+
+```bash
+roo "Task" -e /path/to/extension  -w ~/project
+```
+
+**Use cases:**
+- Testing extension changes
+- Using a specific extension version
+- Development and debugging
+- Custom extension builds
+
+**Default:** Auto-detected from installation
+
+### `--dangerously-skip-permissions`
+
+Skip all permission checks (alias for `-y`).
+
+```bash
+roo ~/project --dangerously-skip-permissions "Task"
+```
+
+:::danger
+Extremely dangerous. Only use in fully controlled environments.
+:::
+
+## Authentication Commands
+
+### `roo auth login`
+
+Authenticate with Roo Code Cloud.
+
+```bash
+roo auth login
+```
+
+**Process:**
+1. Opens browser to Roo Code Cloud
+2. Completes authentication in browser
+3. Receives token via localhost callback
+4. Stores token securely in `~/.config/roo/credentials.json`
+
+**Options:**
+- No additional options
+
+### `roo auth logout`
+
+Clear stored authentication token.
+
+```bash
+roo auth logout
+```
+
+Removes the token from `~/.config/roo/credentials.json`.
+
+### `roo auth status`
+
+Show current authentication status.
+
+```bash
+roo auth status
+```
+
+**Output includes:**
+- Authentication status (logged in or not)
+- Token expiration date
+- Associated account information
+
+**Example output:**
+```
+✓ Authenticated with Roo Code Cloud
+  Token expires: 2026-04-23
+  Account: user@example.com
+```
+
+## Environment Variables
+
+The CLI respects these environment variables:
+
+### API Keys
+
+| Variable | Description |
+| --- | --- |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `OPENROUTER_API_KEY` | OpenRouter API key |
+| `GOOGLE_API_KEY` | Google/Gemini API key |
+
+### Configuration
+
+| Variable | Description |
+| --- | --- |
+| `ROO_WEB_APP_URL` | Custom Roo Code Cloud URL (default: `https://app.roocode.com`) |
+
+### Proxy Support
+
+Standard proxy environment variables are supported:
+
+| Variable | Description |
+| --- | --- |
+| `HTTP_PROXY` | HTTP proxy URL |
+| `HTTPS_PROXY` | HTTPS proxy URL |
+| `NO_PROXY` | Comma-separated list of hosts to exclude from proxy |
+
+## Exit Codes
+
+The CLI uses standard exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | General error |
+| `2` | Invalid arguments or configuration |
+| `130` | Interrupted by user (Ctrl+C) |
+
+**Example in scripts:**
+```bash
+if roo ~/project -y "Run tests"; then
+  echo "Success"
+else
+  echo "Failed with exit code $?"
+fi
+```
+
+## Configuration Files
+
+### Settings File
+
+Location: `~/.config/roo/cli-settings.json`
+
+**Format:**
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code",
+  "reasoningEffort": "medium"
+}
+```
+
+See [Configuration](/cli/configuration) for details.
+
+### Credentials File
+
+Location: `~/.config/roo/credentials.json`
+
+**Format:** (Auto-managed by auth commands)
+```json
+{
+  "token": "...",
+  "expiresAt": "2026-04-23T00:00:00Z"
+}
+```
+
+:::warning
+Never manually edit this file. Use `roo auth` commands.
+:::
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Interactive mode
+roo ~/my-project
+
+# With prompt
+roo "What does this code do?" -w ~/my-project
+
+# Non-interactive
+roo ~/my-project -y "Format all files"
+```
+
+### Provider & Model Selection
+
+```bash
+# Use Anthropic directly
+roo "Task" -p anthropic -m claude-sonnet-4.5  -w ~/project
+
+# Use OpenRouter
+roo "Task" -p openrouter -m anthropic/claude-sonnet-4.5  -w ~/project
+
+# Use OpenAI
+roo "Task" -p openai-native -m gpt-4o  -w ~/project
+```
+
+### Mode Selection
+
+```bash
+# Planning
+roo "Design a new feature" -M architect  -w ~/project
+
+# Implementation
+roo "Implement the feature" -M code  -w ~/project
+
+# Questions
+roo "How does authentication work?" -M ask  -w ~/project
+
+# Debugging
+roo "Why is the login failing?" -M debug  -w ~/project
+```
+
+### Automation
+
+```bash
+# CI/CD
+roo ~/project \
+  -y \
+  --exit-on-complete \
+  --no-tui \
+  "Run linter and fix issues"
+
+# Script with error handling
+if ! roo "Generate docs" -y -x  -w ~/project 2>&1 | tee build.log; then
+  echo "Documentation generation failed"
+  exit 1
+fi
+```
+
+### Complex Workflows
+
+```bash
+# Step 1: Architect mode (interactive)
+roo "Plan user authentication" -M architect  -w ~/project
+
+# Step 2: Code mode (automated)
+roo ~/project -M code -y "Implement the authentication plan"
+
+# Step 3: Ask mode (review)
+roo "Explain the authentication implementation" -M ask  -w ~/project
+```
+
+### Debug and Development
+
+```bash
+# Debug mode
+roo ~/project --debug "Task"
+
+# Custom extension
+roo "Task" -e ./custom-extension  -w ~/project
+
+# Ephemeral (no history)
+roo ~/project --ephemeral "Quick test"
+```
+
+## Common Patterns
+
+### Daily Development
+
+```bash
+# Set defaults in settings file
+cat > ~/.config/roo/cli-settings.json <<EOF
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4.5",
+  "mode": "code"
+}
+EOF
+
+# Then use short commands
+roo "Add tests" -w ~/project
+```
+
+### Shell Aliases
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias roo-quick='roo --ephemeral -y --exit-on-complete'
+alias roo-plan='roo -M architect'
+alias roo-code='roo -M code'
+alias roo-debug='roo -M debug --debug'
+
+# Usage
+roo-quick ~/project "Quick fix"
+roo-plan ~/project "Design feature"
+```
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: AI Code Review
+  env:
+    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+  run: |
+    roo ${{ github.workspace }} \
+      -y \
+      --exit-on-complete \
+      --no-tui \
+      -p openrouter \
+      -m anthropic/claude-sonnet-4.5 \
+      "Review the changes in this PR and report issues"
+```
+
+### Batch Processing
+
+```bash
+#!/bin/bash
+# Process multiple projects
+for project in ~/projects/*; do
+  echo "Processing $project"
+  roo "$project" -y -x --no-tui "Update dependencies" 2>&1 | tee "$project.log"
+done
+```
+
+## Tips
+
+### Performance
+
+- Use `--ephemeral` for faster one-off commands (no state persistence)
+- Choose appropriate reasoning effort (lower = faster, higher = more thorough)
+- Use specific prompts to reduce back-and-forth
+
+### Safety
+
+- Always test in interactive mode before automating with `-y`
+- Use version control before allowing file writes
+- Review logs when using non-interactive mode
+- Start with read-only tasks when learning
+
+### Efficiency
+
+- Set defaults in settings file for repeated options
+- Create shell aliases for common patterns
+- Use modes appropriately (architect → code → debug)
+- Pipe output with `--no-tui` for logging
+
+## Getting Help
+
+### Built-in Help
+
+```bash
+# General help
+roo --help
+
+# Auth commands help
+roo auth --help
+```
+
+### Version Information
+
+```bash
+roo --version
+```
+
+### Support Resources
+
+- **Discord**: [discord.gg/roocode](https://discord.gg/roocode)
+- **GitHub Issues**: [github.com/RooCodeInc/Roo-Code/issues](https://github.com/RooCodeInc/Roo-Code/issues)
+- **Reddit**: [reddit.com/r/RooCode](https://reddit.com/r/RooCode)
+- **Documentation**: [roocode.com/docs](https://roocode.com/docs)
+
+## Next Steps
+
+- [Learn about advanced use cases](/cli/advanced) for complex workflows
+- [Explore configuration options](/cli/configuration) to customize your setup
+- [Read usage patterns](/cli/usage) for interactive vs non-interactive modes
diff --git a/docs/cli/usage.md b/docs/cli/usage.md
new file mode 100644
index 00000000..a3db5905
--- /dev/null
+++ b/docs/cli/usage.md
@@ -0,0 +1,367 @@
+---
+sidebar_label: Usage Modes
+description: Understanding interactive and non-interactive modes in Roo Code CLI
+keywords:
+  - CLI usage
+  - interactive mode
+  - non-interactive mode
+  - automation
+---
+
+# Usage Modes
+
+The Roo Code CLI supports two primary usage modes: interactive and non-interactive. Understanding when and how to use each mode is key to getting the most out of the CLI.
+
+## Interactive Mode (Default)
+
+Interactive mode provides a rich terminal user interface (TUI) with real-time updates and manual approval for all actions.
+
+### Starting Interactive Mode
+
+Run the CLI without the `-y` flag:
+
+```bash
+roo "Analyze the architecture" -w ~/my-project
+```
+
+Or enter the TUI first and provide the prompt:
+
+```bash
+roo ~/my-project
+# Then type your prompt in the TUI
+```
+
+### Interactive Mode Features
+
+**Terminal User Interface**
+- Real-time streaming of AI responses
+- Visual tool execution feedback
+- Progress indicators
+- Syntax-highlighted code blocks
+- Rich text formatting
+
+**Action Approvals**
+The CLI prompts for approval before:
+- Reading files
+- Writing or modifying files
+- Executing commands
+- Opening browsers
+- Using MCP tools
+
+**User Controls**
+- Type `y` or `yes` to approve
+- Type `n` or `no` to reject
+- Type `a` or `always` to approve all future actions of this type
+- Press `Ctrl+C` to cancel the current operation
+- Press `Ctrl+D` to exit
+
+**Follow-up Questions**
+When the AI needs clarification, it presents:
+- Multiple suggested responses
+- Ability to type custom responses
+- Context from the conversation
+
+### Interactive Mode Example
+
+```bash
+$ roo "Refactor the authentication logic" -w ~/my-project
+
+┌─ Roo Code CLI ────────────────────────────────────┐
+│ Mode: code | Model: claude-sonnet-4.5              │
+│                                                    │
+│ 🤔 Analyzing authentication logic...              │
+│                                                    │
+│ 📖 Reading file: src/auth.ts                      │
+│    Allow? (y/n/always): y                         │
+│                                                    │
+│ ✓ Read src/auth.ts (245 lines)                    │
+│                                                    │
+│ 💭 I'll refactor this to use JWT tokens instead   │
+│    of sessions. This will make it stateless and   │
+│    more scalable.                                 │
+│                                                    │
+│ ✏️  Writing file: src/auth.ts                      │
+│    Allow? (y/n/always): y                         │
+│                                                    │
+│ ✓ Wrote src/auth.ts (287 lines)                   │
+│                                                    │
+│ ✅ Refactoring complete!                           │
+└────────────────────────────────────────────────────┘
+```
+
+### When to Use Interactive Mode
+
+Use interactive mode when:
+- **Learning**: Exploring what the CLI can do
+- **Development**: Working on code where you want to review each change
+- **Safety**: Working with critical code that requires careful review
+- **Collaboration**: Pairing with others who want to see the process
+- **Complex Tasks**: Multi-step tasks where you might need to provide guidance
+
+## Non-Interactive Mode
+
+Non-interactive mode auto-approves all actions and is designed for automation and scripts.
+
+### Starting Non-Interactive Mode
+
+Use the `-y` or `--yes` flag:
+
+```bash
+roo ~/my-project -y "Format all TypeScript files"
+```
+
+### Non-Interactive Mode Features
+
+**Auto-Approval**
+All actions are automatically approved:
+- File reads proceed without prompts
+- File writes execute immediately
+- Commands run without confirmation
+- Browser and MCP actions execute automatically
+
+**Follow-up Questions**
+When the AI asks a question:
+- A 60-second countdown timer is displayed
+- If you type anything, the timer cancels and you can provide input
+- If the timer expires, the first suggested response is auto-selected
+
+**Exit Behavior**
+By default, non-interactive mode stays open after completing the task. Use `--exit-on-complete` to exit automatically:
+
+```bash
+roo "Task" -y --exit-on-complete  -w ~/my-project
+```
+
+### Non-Interactive Mode Example
+
+```bash
+$ roo ~/my-project -y "Add error logging to all API routes"
+
+Starting task: Add error logging to all API routes
+Mode: code | Model: claude-sonnet-4.5
+
+Reading src/routes/api.ts... ✓
+Reading src/routes/auth.ts... ✓
+Reading src/routes/users.ts... ✓
+
+Analyzing routes... ✓
+
+Writing src/utils/logger.ts... ✓
+Updating src/routes/api.ts... ✓
+Updating src/routes/auth.ts... ✓
+Updating src/routes/users.ts... ✓
+
+Task completed successfully!
+Added error logging to 3 API routes.
+```
+
+### When to Use Non-Interactive Mode
+
+Use non-interactive mode when:
+- **CI/CD Pipelines**: Automated code reviews, testing, or deployment tasks
+- **Batch Processing**: Processing multiple projects or files
+- **Scheduled Tasks**: Cron jobs or scheduled maintenance
+- **Scripts**: Shell scripts that chain multiple CLI operations
+- **Well-Defined Tasks**: Tasks with clear requirements that don't need oversight
+
+:::warning
+Non-interactive mode will execute all proposed actions without confirmation. Only use it with trusted prompts in controlled environments.
+:::
+
+## Comparison
+
+| Feature | Interactive Mode | Non-Interactive Mode |
+| --- | --- | --- |
+| Action Approval | Manual (y/n prompts) | Automatic (all approved) |
+| User Interface | Rich TUI | Plain text output |
+| Follow-up Questions | Full input capability | 60s timeout → auto-select |
+| Exit After Task | Stays open | Optional (`--exit-on-complete`) |
+| Use Case | Development, learning | Automation, CI/CD |
+| Safety | High (review each action) | Low (executes everything) |
+
+## Switching Between Modes
+
+You cannot switch modes during execution, but you can:
+
+**Start in interactive, test a command:**
+```bash
+roo "Test task" -w ~/project
+```
+
+**Then run the same task non-interactively:**
+```bash
+roo ~/project -y "Test task"
+```
+
+## Advanced Usage Patterns
+
+### Semi-Automated Workflows
+
+Combine interactive and non-interactive for different steps:
+
+```bash
+# Step 1: Plan interactively in architect mode
+roo "Design a new feature" -M architect  -w ~/project
+
+# Step 2: Implement non-interactively in code mode
+roo ~/project -M code -y "Implement the design from the previous task"
+
+# Step 3: Review interactively
+roo "Review the implementation" -M ask  -w ~/project
+```
+
+### Conditional Automation
+
+Use shell logic to decide when to use `-y`:
+
+```bash
+#!/bin/bash
+
+# Check if in CI environment
+if [ "$CI" = "true" ]; then
+  MODE_FLAGS="-y --exit-on-complete --no-tui"
+else
+  MODE_FLAGS=""
+fi
+
+roo ~/project $MODE_FLAGS "Run code quality checks"
+```
+
+### Timeout Handling in Non-Interactive
+
+Handle follow-up questions in scripts:
+
+```bash
+# Non-interactive with immediate auto-selection
+# (Don't wait for 60s timeout)
+echo "" | roo ~/project -y "Task that might ask questions"
+```
+
+### Logging in Non-Interactive Mode
+
+Capture output for logs:
+
+```bash
+roo "Generate docs" -y --no-tui  -w ~/project 2>&1 | tee build.log
+```
+
+## TUI Controls
+
+### Interactive TUI Features
+
+When running in interactive mode, the TUI provides:
+
+**Input Area**
+- Multi-line input support (Shift+Enter for new line)
+- Autocomplete with Tab key
+- Command history with Up/Down arrows
+- File path completion
+
+**Display Area**
+- Streaming AI responses
+- Tool execution visualization
+- Progress indicators
+- Error messages with context
+- Syntax highlighting for code
+
+**Status Bar**
+- Current mode (code, architect, ask, debug)
+- Model being used
+- Token usage and costs
+- Connection status
+
+### Disabling TUI
+
+For plain text output (useful for piping or logging):
+
+```bash
+roo ~/project --no-tui "Task"
+```
+
+This provides:
+- Plain text output without formatting
+- No interactive elements
+- Suitable for redirection or parsing
+- Still requires manual approval unless `-y` is used
+
+## Best Practices
+
+### For Interactive Use
+
+1. **Start Small**: Begin with read-only tasks to understand behavior
+2. **Review Carefully**: Read proposed changes before approving
+3. **Use Always Sparingly**: Only use "always approve" for safe operations
+4. **Ask Questions**: Use follow-up to clarify AI actions
+5. **Save Work First**: Commit or backup before allowing writes
+
+### For Non-Interactive Use
+
+1. **Test First**: Run interactively before automating
+2. **Specific Prompts**: Be explicit about what you want
+3. **Error Handling**: Wrap in scripts with error checking
+4. **Dry Runs**: Consider architect mode first to plan
+5. **Monitor Output**: Log and review execution results
+6. **Limit Scope**: Use specific, bounded tasks
+
+### Hybrid Approach
+
+```bash
+#!/bin/bash
+# review.sh - Interactive planning, automated execution
+
+echo "=== Step 1: Plan (Interactive) ==="
+roo "Plan how to add rate limiting" -M architect  -w ~/project
+
+echo ""
+echo "Proceed with implementation? (y/n)"
+read -r response
+
+if [ "$response" = "y" ]; then
+  echo "=== Step 2: Implement (Automated) ==="
+  roo ~/project -M code -y "Implement rate limiting as planned"
+  
+  echo ""
+  echo "=== Step 3: Review (Interactive) ==="
+  roo "Explain what was implemented" -M ask  -w ~/project
+fi
+```
+
+## Troubleshooting
+
+### Interactive Mode Issues
+
+**TUI Not Rendering Properly**
+```bash
+# Try without TUI
+roo ~/project --no-tui "Task"
+
+# Check terminal compatibility
+echo $TERM
+```
+
+**Approval Prompts Not Working**
+- Ensure stdin is not redirected
+- Check terminal supports interactive input
+- Verify no other processes are blocking input
+
+### Non-Interactive Mode Issues
+
+**Tasks Not Completing**
+```bash
+# Add debug output
+roo "Task" -y --debug  -w ~/project
+
+# Use exit-on-complete
+roo "Task" -y --exit-on-complete  -w ~/project
+```
+
+**Unexpected Approvals**
+- Review your prompt for unintended actions
+- Test in interactive mode first
+- Check what files/commands are being executed with `--debug`
+
+## Next Steps
+
+- [Review the complete CLI reference](/cli/reference) for all available options
+- [Explore advanced use cases](/cli/advanced) for complex workflows
+- [Learn about configuration](/cli/configuration) to set defaults for each mode
diff --git a/sidebars.ts b/sidebars.ts
index 3bd860da..2dc34fb7 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -120,6 +120,20 @@ const sidebars: SidebarsConfig = {
         },
       ],
     },
+    {
+      type: 'category',
+      label: 'Roo Code CLI (Beta)',
+      items: [
+        'cli/overview',
+        'cli/installation',
+        'cli/authentication',
+        'cli/getting-started',
+        'cli/configuration',
+        'cli/usage',
+        'cli/reference',
+        'cli/advanced',
+      ],
+    },
     {
       type: 'category',
       label: 'Roo Code Cloud',
diff --git a/src/css/custom.css b/src/css/custom.css
index 4547ab21..03b19ebb 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -2423,4 +2423,4 @@ a.breadcrumbs__link:hover {
 /* Override Docusaurus default that makes search input 2rem when not focused */
 .navbar__search-input:not(:focus) {
   min-width: 80px !important;
-}
\ No newline at end of file
+}