CLI Commands

O OpenCrabs tem uma CLI completa com mais de 20 subcomandos para gerir todos os aspetos do agente.

Utilização

opencrabs [COMMAND] [OPTIONS]

Comandos

Flags de Configuração

Atalhos de Teclado (TUI)

Prompt de Atualização no Arranque

Quando há uma nova versão disponível, aparece um diálogo centrado no ecrã de splash a perguntar se aceitas (Enter) ou saltas (Esc). Aceitar dispara o /evolve automaticamente. Após a atualização, o binário reinicia e o splash mostra a nova versão.

Comandos de Channel

O /doctor, /help, /usage, /evolve, /restart, /exit e os comandos de sistema funcionam diretamente no Telegram, Discord, Slack e WhatsApp sem passar pelo LLM. Executam instantaneamente e devolvem os resultados no channel.

O /restart e o /exit anunciam-se antes de agir, porque depois de o processo desaparecer não sobra nada para reportar uma falha. Ambos são só do owner, como todos os comandos que alteram o processo em execução. O /exit é o único comando sem caminho de volta a partir do chat, a recuperação precisa de acesso à máquina onde o OpenCrabs corre.

Desde a v0.3.80, um stop falado também é respeitado, dizer ao bot para parar em linguagem natural funciona nos channels e no TUI, não só a palavra seca “stop”.

Toda a lógica de comandos de channel está centralizada em src/channels/commands.rs (847 linhas), um handler partilhado que elimina lógica de comandos duplicada por 5 implementações de channel. Cada channel delega em try_execute_text_command() para comportamento consistente.

O /evolve nos channels agora corre diretamente (descarrega + instala o binário) sem exigir uma ida-e-volta ao LLM. Antes era encaminhado pelo agente.

Modo Chat

# Predefinição: lançar o TUI
opencrabs

# Igual ao anterior
opencrabs chat

Modo Agent

Modo não interativo para scripting e automação:

# Chat interativo multi-turn
opencrabs agent

# Modo de mensagem única
opencrabs agent -m "What files changed today?"

Modo Daemon vs TUI

O OpenCrabs corre num de dois modos. Escolhe o que encaixa na máquina. Para qualquer profile, corre só um de cada vez.

Porque não ambos ao mesmo tempo?

Uma credencial de bot (ex.: um token do Telegram) só consegue suster um poll getUpdates ativo. Se um daemon e um TUI forem ambos donos do token do mesmo profile, eles brigam (HTTP 409) e o channel cai.

O TUI ganha sempre

Quando abres o TUI enquanto um daemon do mesmo profile está a correr, o TUI primeiro desliga esse daemon, assume os channels e mostra um banner a dizê-lo. Os teus channels já estavam configurados, por isso simplesmente retomam, sem reconectar. O daemon fica em baixo até o voltares a iniciar (opencrabs service start, ou relançar opencrabs daemon).

Numa máquina onde o daemon costuma correr, o fluxo do dia-a-dia é: abre opencrabs quando te queres sentar com ele; fecha o TUI e opencrabs service start quando o queres outra vez headless.

Arranque automático no boot

• Daemon: usa o instalador de serviço (opencrabs service install); liga o systemd (Linux) / launchd (macOS) para arrancar no boot e reiniciar em crash. Esta é a configuração always-on recomendada.
• TUI: para a interface de terminal abrir automaticamente no login, usa um autostart de terminal/desktop, não o instalador de serviço:
  • Desktop Linux: pousa um ficheiro .desktop em ~/.config/autostart/ com Exec=x-terminal-emulator -e opencrabs.
  • macOS: Definições do Sistema > Geral > Itens de Início de Sessão > adiciona um script .command que corre opencrabs.
  • VPS por SSH: corre dentro de tmux/screen e reanexa. Numa VPS headless normalmente queres o daemon, não o TUI.

Fortemente recomendado para utilizadores do dia-a-dia. Se planeias usar o OpenCrabs diariamente, pede-lhe para se configurar como serviço de sistema. Basta dizer algo como “configura-te para arrancar com o meu computador” ou “remove o serviço de arranque automático”. O agente trata da configuração e remoção do launchd (macOS) ou systemd (Linux) automaticamente por ti.

Manter o TUI a correr numa VPS (tmux)

Se queres o TUI interativo completo sempre disponível num servidor remoto (não o daemon headless), tmux é o caminho. A tua session sobrevive a desconexões SSH, sleep do laptop e ligações instáveis.

1. Instala o tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Descobre onde o opencrabs está instalado

which opencrabs

# Se isso não devolver nada, pesquisa todo o sistema de ficheiros
find / -name "opencrabs" -type f 2>/dev/null

3. Inicia uma session de tmux com nome

tmux new -s opencrabs

4. Lança o opencrabs lá dentro

opencrabs

5. Desanexa (deixa o opencrabs a correr)

Prime Ctrl+B e depois D. Já podes fechar o SSH e o opencrabs continua a correr.

6. Reanexa mais tarde

tmux attach -t opencrabs

É isto. Volta de qualquer máquina, reanexa e continua onde ficaste. Se só precisas dos channels (Telegram, Discord, Slack, WhatsApp) a correr headless sem o TUI, o daemon encaixa melhor: opencrabs service install && opencrabs service start.

Endpoint de Saúde

Adiciona ao config.toml para expor um health check:

[daemon]
health_port = 8080

Depois GET http://localhost:8080/health devolve 200 OK com estado em JSON. Útil para watchdog de systemd, monitores de uptime ou load balancers.

Gestão de Serviço

Instala o OpenCrabs como serviço de sistema (launchd no macOS, systemd no Linux):

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

Serviços com noção de profile

Cada profile recebe o seu próprio serviço independente:

# Instala um profile específico como serviço
opencrabs -p hermes service install
opencrabs -p hermes service start

# Cada profile recebe o seu próprio nome de serviço
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Gere de forma independente
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Vários profiles podem correr como serviços daemon simultâneos com isolamento total.

Variável de ambiente OPENCRABS_PROFILE

Define OPENCRABS_PROFILE=hermes para selecionar um profile sem a flag -p. Útil para serviços systemd, cron jobs e modo daemon.

Resolução de problemas: o daemon não levanta

Se o opencrabs service status diz stopped:

1. Abreste o TUI? Abrir o opencrabs desliga deliberadamente o daemon para que a session interativa seja dona dos channels. O daemon fica em baixo até correres opencrabs service start outra vez.
2. Builds antigas podem ainda ter Restart=on-failure em vez de Restart=always. Regenera a unit com opencrabs service install (depois service start) para adotar a política de reinício permanente.
3. Config, chaves, comandos e ferramentas fazem hot-reload em runtime. Editar o config.toml ou o keys.toml nunca precisa de reiniciar o daemon. Se uma alteração não está a surtir efeito, verifica nos logs uma linha ConfigWatcher: reloaded em vez de reiniciar.

Gestão de Cron

# Listar todos os cron jobs
opencrabs cron list

# Adicionar um novo 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"

Atalhos de Teclado do TUI