CLI Commands

OpenCrabs a une CLI complète avec plus de 20 sous-commandes pour gérer chaque aspect de l’agent.

Utilisation

opencrabs [COMMAND] [OPTIONS]

Commandes

Flags de configuration

Raccourcis clavier (TUI)

Invite de mise à jour au démarrage

Quand une nouvelle version est disponible, un dialogue centré apparaît sur l’écran de splash pour accepter (Entrée) ou passer (Échap). Accepter déclenche /evolve automatiquement. Après la mise à jour, le binaire redémarre et le splash affiche la nouvelle version.

Commandes de channel

Le /doctor, /help, /usage, /evolve, /restart, /exit et les commandes système fonctionnent directement sur Telegram, Discord, Slack et WhatsApp sans passer par le LLM. Elles s’exécutent instantanément et renvoient les résultats dans le channel.

Le /restart et le /exit s’annoncent avant d’agir, parce qu’une fois le processus disparu, il ne reste rien pour signaler un échec. Les deux sont réservés au owner, comme chaque commande qui modifie le processus en cours. Le /exit est l’unique commande sans retour depuis le chat, la récupération nécessite l’accès à la machine où tourne OpenCrabs.

Depuis la v0.3.80, un stop parlé est aussi respecté, dire au bot d’arrêter en langage naturel fonctionne sur les channels et dans le TUI, pas seulement le mot sec « stop ».

Toute la logique de commandes de channel est centralisée dans src/channels/commands.rs (847 lignes), un handler partagé qui élimine la logique dupliquée à travers 5 implémentations de channel. Chaque channel délègue à try_execute_text_command() pour un comportement cohérent.

Le /evolve sur les channels s’exécute maintenant directement (télécharge + installe le binaire) sans demander d’aller-retour LLM. Auparavant il passait par l’agent.

Mode chat

# Par défaut: lancer le TUI
opencrabs

# Identique à ci-dessus
opencrabs chat

Mode agent

Mode non interactif pour le scripting et l’automatisation :

# Chat interactif multi-turn
opencrabs agent

# Mode message unique
opencrabs agent -m "What files changed today?"

Mode daemon vs TUI

OpenCrabs tourne dans un de deux modes. Choisissez celui qui convient à la machine. Pour un profile donné, n’en lancez qu’un à la fois.

Pourquoi pas les deux à la fois ?

Une credential de bot (ex. un token Telegram) ne peut tenir qu’un seul poll getUpdates actif. Si un daemon et un TUI possèdent tous deux le token du même profile, ils se battent (HTTP 409) et le channel tombe.

Le TUI gagne toujours

Quand vous ouvrez le TUI pendant qu’un daemon du même profile tourne, le TUI ferme d’abord ce daemon, reprend les channels et affiche un banner pour le dire. Vos channels étaient déjà configurés, donc ils reprennent simplement, sans reconnexion. Le daemon reste éteint jusqu’à ce que vous le relanciez (opencrabs service start, ou relancez opencrabs daemon).

Sur une machine où le daemon tourne habituellement, le flux quotidien est : ouvrez opencrabs quand vous voulez vous y mettre ; fermez le TUI et opencrabs service start quand vous le voulez à nouveau headless.

Démarrage auto au boot

• Daemon: utilisez l’installeur de service (opencrabs service install) ; il câble systemd (Linux) / launchd (macOS) pour démarrer au boot et redémarrer après un plantage. C’est la configuration always-on recommandée.
• TUI: pour que l’interface terminal s’ouvre automatiquement à la connexion, utilisez un autostart de terminal/desktop, pas l’installeur de service :
  • Desktop Linux : déposez un fichier .desktop dans ~/.config/autostart/ avec Exec=x-terminal-emulator -e opencrabs.
  • macOS : Réglages Système > Général > Éléments de connexion > ajoutez un script .command qui lance opencrabs.
  • VPS par SSH : tournez dans tmux/screen et rattachez-vous. Sur un VPS headless, vous voulez généralement le daemon, pas le TUI.

Fortement recommandé pour les utilisateurs quotidiens. Si vous comptez utiliser OpenCrabs tous les jours, demandez-lui de s’installer comme service système. Dites simplement « installe-toi pour démarrer avec mon ordinateur » ou « retire le service de démarrage auto ». L’agent gère la mise en place et la suppression launchd (macOS) ou systemd (Linux) automatiquement pour vous.

Garder le TUI actif sur un VPS (tmux)

Si vous voulez le TUI interactif complet toujours disponible sur un serveur distant (pas le daemon headless), tmux est la solution. Votre session survit aux déconnexions SSH, à la veille du laptop et aux connexions capricieuses.

1. Installez tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Trouvez où opencrabs est installé

which opencrabs

# Si cela ne renvoie rien, cherchez tout le système de fichiers
find / -name "opencrabs" -type f 2>/dev/null

3. Démarrez une session tmux nommée

tmux new -s opencrabs

4. Lancez opencrabs dedans

opencrabs

5. Détachez (opencrabs continue de tourner)

Pressez Ctrl+B puis D. Vous pouvez maintenant fermer SSH et opencrabs continue de tourner.

6. Rattachez-vous plus tard

tmux attach -t opencrabs

C’est tout. Revenez de n’importe quelle machine, rattachez-vous, et reprenez où vous en étiez. Si vous n’avez besoin que des channels (Telegram, Discord, Slack, WhatsApp) en headless sans le TUI, le daemon convient mieux : opencrabs service install && opencrabs service start.

Endpoint de santé

Ajoutez au config.toml pour exposer un health check :

[daemon]
health_port = 8080

Ensuite GET http://localhost:8080/health renvoie 200 OK avec un statut JSON. Utile pour un watchdog systemd, des moniteurs d’uptime ou des load balancers.

Gestion du service

Installez OpenCrabs comme service système (launchd sur macOS, systemd sur Linux) :

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

Services sensibles au profile

Chaque profile reçoit son propre service indépendant :

# Installer un profile précis comme service
opencrabs -p hermes service install
opencrabs -p hermes service start

# Chaque profile reçoit son propre nom de service
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Gérer indépendamment
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Plusieurs profiles peuvent tourner comme services daemon simultanés avec isolation complète.

Variable d’environnement OPENCRABS_PROFILE

Définissez OPENCRABS_PROFILE=hermes pour sélectionner un profile sans le flag -p. Utile pour les services systemd, les cron jobs et le mode daemon.

Dépannage : le daemon ne remonte pas

Si opencrabs service status dit stopped :

1. Avez-vous ouvert le TUI ? Ouvrir opencrabs éteint délibérément le daemon pour que la session interactive possède les channels. Le daemon reste éteint jusqu’à ce que vous relanciez opencrabs service start.
2. Les anciennes builds peuvent encore avoir Restart=on-failure au lieu de Restart=always. Régénérez l’unit avec opencrabs service install (puis service start) pour adopter la politique de redémarrage permanent.
3. Config, clés, commandes et outils se rechargent à chaud à l’exécution. Éditer config.toml ou keys.toml ne nécessite jamais de redémarrage du daemon. Si un changement ne prend pas effet, cherchez dans les logs une ligne ConfigWatcher: reloaded plutôt que de redémarrer.

Gestion du cron

# Lister tous les cron jobs
opencrabs cron list

# Ajouter un nouveau 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"

Raccourcis clavier du TUI