CLI Commands

OpenCrabs tiene una CLI completa con más de 20 subcomandos para gestionar todos los aspectos del agente.

Uso

opencrabs [COMMAND] [OPTIONS]

Comandos

Flags de Configuración

Atajos de Teclado (TUI)

Aviso de Actualización al Arrancar

Cuando hay una versión nueva disponible, aparece un diálogo centrado en la pantalla de splash pidiendo aceptar (Enter) o saltar (Esc). Aceptar dispara /evolve automáticamente. Tras la actualización, el binario se reinicia y el splash muestra la nueva versión.

Comandos de Canal

/doctor, /help, /usage, /evolve, /restart, /exit y los comandos de sistema funcionan directamente en Telegram, Discord, Slack y WhatsApp sin pasar por el LLM. Se ejecutan al instante y devuelven resultados en el canal.

/restart y /exit se anuncian antes de actuar, porque una vez que el proceso desaparece no queda nada que reporte un fallo. Ambos son solo-owner, como cualquier otro comando que cambia el proceso en ejecución. /exit es el único comando sin retorno desde el chat: recuperar requiere acceso a la máquina donde corre OpenCrabs.

Desde v0.3.80, un stop hablado también se respeta, decirle al bot que pare en lenguaje natural funciona en los canales y en la TUI, no solo la palabra suelta “stop”.

Toda la lógica de comandos de canal está centralizada en src/channels/commands.rs (847 líneas), un handler compartido que elimina la lógica duplicada entre 5 implementaciones de canal. Cada canal delega en try_execute_text_command() para un comportamiento consistente.

/evolve en los canales ahora se ejecuta directamente (descarga + instala el binario) sin requerir un round-trip al LLM. Antes se enrutaba a través del agente.

Modo Chat

# Default: launch TUI
opencrabs

# Same as above
opencrabs chat

Modo Agente

Modo no interactivo para scripting y automatización:

# Interactive multi-turn chat
opencrabs agent

# Single-message mode
opencrabs agent -m "What files changed today?"

Modo Daemon vs TUI

OpenCrabs corre en uno de dos modos. Elige el que encaje con la máquina. Para un mismo perfil, ejecuta solo uno a la vez.

¿Por qué no ambos a la vez?

Una credencial de bot (p. ej. un token de Telegram) solo puede mantener un poll getUpdates vivo. Si un daemon y una TUI poseen el token del mismo perfil, se pelean (HTTP 409) y el canal se cae.

La TUI siempre gana

Cuando abres la TUI mientras corre un daemon del mismo perfil, la TUI apaga ese daemon primero, toma los canales y muestra un banner avisando de ello. Tus canales ya estaban configurados, así que simplemente se reanudan, sin reconectar. El daemon permanece apagado hasta que lo arranques de nuevo (opencrabs service start, o relanza opencrabs daemon).

En una máquina donde el daemon suele correr, el flujo diario es: abre opencrabs cuando quieras sentarte con él; cierra la TUI y opencrabs service start cuando lo quieras headless de nuevo.

Autoarranque al encender

• Daemon: usa el instalador de servicio (opencrabs service install); conecta systemd (Linux) / launchd (macOS) para arrancar al encender y reiniciar ante fallos. Esta es la configuración always-on recomendada.
• TUI: para que la interfaz de terminal se abra automáticamente al iniciar sesión, usa un autoarranque de terminal/escritorio, no el instalador de servicio:
  • Escritorio Linux: deja un archivo .desktop en ~/.config/autostart/ con Exec=x-terminal-emulator -e opencrabs.
  • macOS: Ajustes del Sistema > General > Elementos de Inicio > añade un script .command que ejecute opencrabs.
  • VPS por SSH: ejecuta dentro de tmux/screen y reengánchate. En un VPS headless normalmente quieres el daemon, no la TUI.

Muy recomendado para usuarios diarios. Si planeas usar OpenCrabs a diario, pídele que se configure como servicio del sistema. Solo di algo como “configúrate para arrancar con mi ordenador” o “quita el servicio de autoarranque”. El agente gestiona la configuración y eliminación de launchd (macOS) o systemd (Linux) automáticamente.

Mantén la TUI corriendo en un VPS (tmux)

Si quieres la TUI interactiva completa siempre disponible en un servidor remoto (no el daemon headless), tmux es el camino. Tu sesión sobrevive a desconexiones SSH, suspensión del portátil y conexiones inestables.

1. Instala tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Localiza dónde está instalado opencrabs

which opencrabs

# If that returns nothing, search the whole filesystem
find / -name "opencrabs" -type f 2>/dev/null

3. Arranca una sesión tmux con nombre

tmux new -s opencrabs

4. Lanza opencrabs dentro

opencrabs

5. Desconéctate (opencrabs sigue corriendo)

Pulsa Ctrl+B y luego D. Ya puedes cerrar SSH y opencrabs sigue corriendo.

6. Reengánchate después

tmux attach -t opencrabs

Eso es todo. Vuelve desde cualquier máquina, reengánchate y continúa donde lo dejaste. Si solo necesitas canales (Telegram, Discord, Slack, WhatsApp) corriendo headless sin la TUI, el daemon encaja mejor: opencrabs service install && opencrabs service start.

Endpoint de Salud

Añade a config.toml para exponer un chequeo de salud:

[daemon]
health_port = 8080

Entonces GET http://localhost:8080/health devuelve 200 OK con estado en JSON. Útil para watchdog de systemd, monitores de uptime o balanceadores.

Gestión del Servicio

Instala OpenCrabs como servicio del sistema (launchd en macOS, systemd en Linux):

opencrabs service install
opencrabs service start
opencrabs service stop
opencrabs service restart
opencrabs service status
opencrabs service uninstall

Servicios conscientes de perfil

Cada perfil recibe su propio servicio independiente:

# Install a specific profile as a service
opencrabs -p hermes service install
opencrabs -p hermes service start

# Each profile gets its own service name
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Manage independently
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Varios perfiles pueden correr como servicios daemon simultáneos con aislamiento total.

Variable de entorno OPENCRABS_PROFILE

Define OPENCRABS_PROFILE=hermes para seleccionar un perfil sin el flag -p. Útil para servicios systemd, cron jobs y modo daemon.

Solución de problemas: el daemon no arranca

Si opencrabs service status dice stopped:

1. ¿Abriste la TUI? Abrir opencrabs apaga deliberadamente el daemon para que la sesión interactiva posea los canales. El daemon permanece apagado hasta que hagas opencrabs service start de nuevo.
2. Las builds antiguas pueden tener aún Restart=on-failure en vez de Restart=always. Regenera la unidad con opencrabs service install (luego service start) para adoptar la política de reinicio siempre.
3. La config, las claves, los comandos y las herramientas se recargan en caliente en tiempo de ejecución. Editar config.toml o keys.toml nunca necesita reiniciar el daemon. Si un cambio no surte efecto, busca en los logs una línea ConfigWatcher: reloaded en vez de reiniciar.

Gestión de Cron

# List all cron jobs
opencrabs cron list

# Add a new cron job
opencrabs cron add \
  --name "Daily Report" \
  --cron "0 9 * * *" \
  --tz "America/New_York" \
  --prompt "Check emails and summarize" \
  --provider anthropic \
  --model claude-sonnet-4-20250514 \
  --thinking off \
  --deliver-to telegram:123456

# Remove a cron job (accepts name or ID)
opencrabs cron remove "Daily Report"

# Enable/disable (accepts name or ID)
opencrabs cron enable "Daily Report"
opencrabs cron disable "Daily Report"

Atajos de Teclado de la TUI