# Genie CLI Automation Guide Complete reference for using Genie CLI in automated workflows (cron, CI/CD, scripts). ## Quick Reference Table | Command | Mode | Output | Use Case | |---------|------|--------|----------| | `genie task` | Headless | JSON | Fire-and-forget tasks | | `genie run` | Foreground | JSON/Text | Wait for completion | | `genie run --background` | Headless | URL | Same as task | | `genie task monitor ` | Foreground | Live logs | Monitor background task | | `genie list tasks` | Query | Table | Task status check | | `genie view ` | Query | Transcript | Get task output | | `genie resume ` | Interactive | JSON | Continue conversation | | `genie stop ` | Control | - | Kill running task | | `genie status` | Health | Status | System health check | --- ## 1. Fire-and-Forget Tasks (Cron/Background) **Command:** `genie task` - Starts task immediately - Returns task ID - No browser, no waiting - Perfect for cron ### Basic Usage ```bash # Default: JSON output with task info genie task code/explore "Check system health" # Output: { "task_id": "abc-123...", "task_url": "http://localhost:8887/...", "agent": "code/explore", "executor": "CLAUDE_CODE:DEFAULT", "status": "started" } ``` ### Quiet Mode (No Warnings) ```bash # Suppress version warnings (clean cron logs) genie task --quiet code/explore "Silent task" ``` ### Cron Examples ```bash # Every 5 minutes - health check */5 * * * * genie task --quiet code/explore "Health check" >> /var/log/genie.log 2>&1 # Daily at 3 AM - cleanup 0 3 * * * genie task --quiet code/code-garbage-collector "Daily cleanup" >> /var/log/cleanup.log 2>&1 # Hourly - save task ID for later monitoring 0 * * * * genie task --quiet code/explore "Hourly scan" | jq -r '.task_id' > /var/log/last-task-id.txt 2>&1 ``` --- ## 2. Wait for Completion (Synchronous) **Command:** `genie run` - Waits for task to finish - Returns output when done - Opens browser (unless --background) ### Basic Usage ```bash # Wait for completion, see output genie run code/explore "Analyze codebase" # Output: Full results JSON with status ``` ### Background Mode ```bash # Same as 'genie task' (no waiting) genie run --background code/explore "Background task" ``` ### Automation Examples ```bash # CI/CD: Run tests and capture results genie run --quiet code/tests "Run all tests" > test-results.json # Script: Wait for analysis, then act on results genie run --quiet code/analyze "Check dependencies" > deps.json if grep -q "vulnerable" deps.json; then echo "Security issues found!" exit 1 fi ``` --- ## 3. Monitor Background Tasks **Command:** `genie task monitor ` - Attach to running task - Stream live logs - Wait for completion ### Usage ```bash # Start task in background TASK_ID=$(genie task --quiet code/explore "Long analysis" | jq -r '.task_id') # Monitor it later genie task monitor $TASK_ID ``` ### Automation Example ```bash # Cron: Start task, then monitor in separate job # Job 1 (every hour): Start task 0 * * * * genie task --quiet code/explore "Hourly check" | jq -r '.task_id' > /tmp/task-id.txt # Job 2 (5 mins later): Monitor completion 5 * * * * genie task monitor $(cat /tmp/task-id.txt) >> /var/log/monitored.log 2>&1 ``` --- ## 4. Query Task Status ### List All Tasks ```bash # Show all tasks (table format) genie list tasks # Sample output: | Task ID | Agent | Status | Executor | |--------------|--------------|---------|------------------| | abc-123... | code/explore | running | CLAUDE_CODE/DEFAULT | ``` ### View Task Output ```bash # Get full transcript genie view # Live view (auto-refresh) genie view --live # Full history genie view --full ``` ### Automation Examples ```bash # Check if any tasks are still running if genie list tasks | grep -q "running"; then echo "Tasks still in progress" fi # Get specific task result genie view abc-123 > task-output.txt ``` --- ## 5. Task Control ### Stop Running Task ```bash genie stop ``` ### Resume Conversation ```bash # Continue from previous task genie resume "Follow-up question" ``` --- ## 6. System Health Checks ### Check Genie Status ```bash genie status # Output: 🧞 GENIE STATUS 📦 Forge Backend: 🟢 Running 📡 MCP Server: ... ``` ### Automation Example ```bash # Pre-flight check before running tasks if ! genie status | grep -q "🟢 Running"; then echo "Forge not running, starting..." genie & # Start Genie server sleep 5 fi # Now safe to run tasks genie task code/explore "Check system" ``` --- ## 7. Executor Control ### Override Default Executor ```bash # Use specific executor genie task -x OPENCODE code/explore "Use OpenCode" genie task --executor GEMINI code/explore "Use Gemini" # Use specific model genie task -m "gpt-4" code/explore "Use GPT-4" ``` ### Automation Example ```bash # Distribute load across executors for executor in CLAUDE_CODE OPENCODE GEMINI; do genie task -x $executor code/explore "Check $executor" & done wait # Wait for all background tasks ``` --- ## 8. Advanced Patterns ### Parallel Execution ```bash # Run multiple tasks simultaneously genie task code/explore "Task 1" & genie task code/analyze "Task 2" & genie task code/tests "Task 3" & wait # Wait for all to finish ``` ### Error Handling ```bash # Capture exit code genie run --quiet code/tests "Run tests" EXIT_CODE=$? if [ $EXIT_CODE -ne 0 ]; then echo "Task failed with code $EXIT_CODE" # Notify, retry, etc. fi ``` ### Task Chaining ```bash # Sequential tasks with error checking TASK1=$(genie task --quiet code/explore "Step 1" | jq -r '.task_id') genie task monitor $TASK1 || exit 1 TASK2=$(genie task --quiet code/analyze "Step 2" | jq -r '.task_id') genie task monitor $TASK2 || exit 1 echo "Pipeline complete!" ``` ### Retry Logic ```bash # Retry failed tasks MAX_RETRIES=3 RETRY=0 while [ $RETRY -lt $MAX_RETRIES ]; do genie run --quiet code/tests "Run tests" && break RETRY=$((RETRY + 1)) echo "Retry $RETRY/$MAX_RETRIES" sleep 10 done ``` --- ## 9. CI/CD Integration ### GitHub Actions Example ```yaml - name: Run Genie Analysis run: | genie task --quiet code/analyze "Analyze PR changes" > task.json TASK_ID=$(jq -r '.task_id' task.json) genie task monitor $TASK_ID ``` ### Jenkins Example ```groovy stage('Genie Quality Check') { steps { sh 'genie run --quiet code/code-quality "Check code quality" > report.json' archiveArtifacts 'report.json' } } ``` --- ## 10. Logging & Output ### Structured Logging ```bash # JSON output for parsing genie task code/explore "Check" | jq '.task_id' # Human-readable output genie run code/explore "Generate report" | tee report.json ``` ### Log Rotation ```bash # Cron with log rotation */15 * * * * genie task --quiet code/explore "Check" >> /var/log/genie/$(date +\%Y\%m\%d).log 2>&1 # Keep last 7 days find /var/log/genie/ -name "*.log" -mtime +7 -delete ``` --- ## Best Practices 1. **Use `--quiet`** in cron to suppress version warnings 2. **Use `jq`** to extract specific fields from JSON output 3. **Check `genie status`** before heavy automation 4. **Save task IDs** for later monitoring/debugging 5. **Use JSON output** for programmatic parsing 6. **Set explicit executor** if you need consistency 7. **Monitor long tasks** via `genie task monitor` 8. **Handle errors** - check exit codes in scripts --- ## Common Issues **Workspace Version Warning:** ```bash ⚠️ Workspace behind: workspace 2.5.19 ← global 2.5.20 ``` Solution: Use `--quiet` flag or run `genie` once to sync. **Forge Not Running:** ```bash ❌ Forge backend unreachable ``` Solution: Start Forge with `genie` (no args) or check `genie status`. **Task Stuck:** ```bash genie stop # Kill stuck task genie list tasks # Check status ```