Cap 8: Orca CLI

El CLI de Orca

Además de la aplicación gráfica, Orca incluye un CLI completo que permite ejecutar todas las operaciones desde terminal. Esto es esencial para automatización, scripting y flujos CI/CD.

orca --help

Orca CLI - Multi-agent IDE orchestrator

USAGE:
    orca <COMMAND> [OPTIONS]

COMMANDS:
    run          Ejecutar un agente en un worktree
    worktree     Gestionar worktrees
    agent        Gestionar agentes
    pr           Pull requests
    issue        Issues de GitHub
    ci           CI/CD status
    merge        Merge worktree a main
    plan         Ejecutar planes multi-agente
    browser      Browser integrado
    screenshot   Capturar pantalla
    config       Configuración
    status       Estado de agentes y worktrees

Comandos principales

orca run

El comando más usado. Lanza un agente en un worktree:

# Crear worktree + lanzar agente
orca run --agent claude --branch feat/auth "Implementa login con JWT"

# Usar worktree existente
orca run --agent codex --worktree fix-api "Corrige el error de timeout"

# Lanzar en background (no bloquea la terminal)
orca run --agent claude --branch feat/auth --detach "Implementa login"

Opciones:

Flag	Descripción
--agent	Agente a usar (claude, codex, gemini, aider)
--branch	Nombre del branch (crea worktree automáticamente)
--worktree	Worktree existente donde ejecutar
--detach	Ejecutar en background
--timeout	Timeout en minutos (default: sin límite)
--env	Variables de entorno adicionales

orca worktree

Gestión de worktrees:

# Crear
orca worktree create feat/auth
orca worktree create feat/auth --base develop  # base diferente a main

# Listar
orca worktree list

# Cambiar al worktree
orca worktree switch feat-auth

# Eliminar
orca worktree remove feat-auth
orca worktree remove feat-auth --force  # con cambios sin commit

# Limpiar worktrees huérfanos
orca worktree prune

orca agent

Gestión de agentes activos:

# Listar agentes corriendo
orca agent list

# Pausar/reanudar
orca agent pause feat-auth
orca agent resume feat-auth

# Detener
orca agent stop feat-auth
orca agent stop --all

# Ver logs de un agente
orca agent logs feat-auth
orca agent logs feat-auth --follow  # streaming

orca status

Vista general del estado:

orca status

PROJECT: mi-proyecto
BRANCH:  main (up to date with origin)

WORKTREES:
  feat-auth      Claude Code    running     2m 30s
  fix-api        Codex          completed   5m 00s
  refactor-ui    -              idle        -

AGENTS: 2 active, 1 completed
TOKENS: 156K used this session

orca merge

Merge de worktree a main:

# Merge simple
orca merge feat-auth

# Merge con squash
orca merge feat-auth --squash

# Merge sin eliminar el worktree
orca merge feat-auth --keep-worktree

# Dry run (muestra qué haría sin ejecutar)
orca merge feat-auth --dry-run

orca plan

Ejecución de planes multi-agente:

# Ejecutar plan
orca plan run plan.yaml

# Validar plan sin ejecutar
orca plan validate plan.yaml

# Ver estado del plan
orca plan status

# Cancelar plan en ejecución
orca plan cancel

Scripting y automatización

Combinar con shell

# Lanzar 5 agentes para corregir issues abiertos
for issue in $(gh issue list -l bug --json number -q '.[].number' | head -5); do
  orca run --agent claude --branch "fix/issue-$issue" --detach \
    "$(gh issue view $issue --json body -q '.body')"
done

Esperar a que un agente termine

# Bloquea hasta que el agente complete
orca agent wait feat-auth

# Con timeout
orca agent wait feat-auth --timeout 10m

Pipeline automatizado

#!/bin/bash
# pipeline.sh - Flujo automatizado completo

# 1. Crear worktree y lanzar agente
orca run --agent claude --branch feat/auth --detach \
  "Implementa autenticación OAuth con Google"

# 2. Esperar a que termine
orca agent wait feat-auth

# 3. Verificar que no hay errores
if [ $? -eq 0 ]; then
  # 4. Ejecutar tests
  cd "$(orca worktree path feat-auth)"
  bun test

  if [ $? -eq 0 ]; then
    # 5. Crear PR
    orca pr create --worktree feat-auth
    echo "PR creado exitosamente"
  else
    echo "Tests fallaron, revisar manualmente"
  fi
else
  echo "Agente falló, revisar logs"
  orca agent logs feat-auth
fi

Configuración del CLI

Archivo de configuración

Orca lee configuración de ~/.orca/config.json y .orca/config.json en la raíz del proyecto:

{
  "defaultAgent": "claude",
  "worktreeDir": "../{project}-orca-wt",
  "concurrency": {
    "maxAgents": 4
  },
  "agents": {
    "claude": {
      "command": "claude",
      "args": ["--dangerously-skip-permissions"]
    },
    "codex": {
      "command": "codex",
      "args": ["--full-auto"]
    }
  },
  "github": {
    "defaultLabels": ["ai-generated"],
    "autoCreatePR": false
  }
}

Variables de entorno

Variable	Descripción
ORCA_HOME	Directorio de configuración (default: ~/.orca)
ORCA_DEFAULT_AGENT	Agente por defecto
ORCA_MAX_AGENTS	Máximo de agentes concurrentes
ORCA_WORKTREE_DIR	Directorio base para worktrees

Autocompletado

Instala autocompletado para tu shell:

# Bash
orca completion bash >> ~/.bashrc

# Zsh
orca completion zsh >> ~/.zshrc

# Fish
orca completion fish > ~/.config/fish/completions/orca.fish

Formato de salida

El CLI soporta múltiples formatos de salida para integración con otras herramientas:

# JSON (para scripting)
orca status --format json

# Table (default, para humanos)
orca status --format table

# Quiet (solo datos esenciales)
orca status --quiet

Buenas prácticas

1. Scripts versionados: guarda tus scripts de Orca en el repo para que el equipo los reutilice
2. Plans como código: define planes YAML en el repo para tareas recurrentes
3. Detach para múltiples: usa --detach cuando lances varios agentes
4. Logs para debug: revisa orca agent logs cuando algo falla
5. JSON para CI: usa --format json en pipelines automatizados