CLI Commands

OpenCrabs has a full CLI with 20+ subcommands for managing every aspect of the agent.

Usage

opencrabs [COMMAND] [OPTIONS]

Commands

Configuration Flags

Keyboard Shortcuts (TUI)

Startup Update Prompt

When a new version is available, a centered dialog appears on the splash screen asking you to accept (Enter) or skip (Esc). Accepting triggers /evolve automatically. After update, the binary restarts and the splash shows the new version.

Channel Commands

/doctor, /help, /usage, /evolve, and system commands work directly on Telegram, Discord, Slack, and WhatsApp without going through the LLM. They execute instantly and return results in the channel.

All channel command logic is centralized in src/channels/commands.rs (847 lines) – a shared handler that eliminates duplicated command logic across 5 channel implementations. Each channel delegates to try_execute_text_command() for consistent behavior.

/evolve on channels now runs directly (downloads + installs the binary) without requiring an LLM round-trip. Previously it was routed through the agent.

Chat Mode

# Default — launch TUI
opencrabs

# Same as above
opencrabs chat

Agent Mode

Non-interactive mode for scripting and automation:

# Interactive multi-turn chat
opencrabs agent

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

Daemon Mode vs TUI

OpenCrabs runs in one of two modes. Pick the one that fits the machine. For any one profile, run only one at a time.

Why not both at once?

A bot credential (e.g. a Telegram token) can only hold one live getUpdates poll. If a daemon and a TUI both own the same profile’s token they fight (HTTP 409) and the channel drops.

The TUI always wins

When you open the TUI while a daemon for the same profile is running, the TUI shuts that daemon down first, takes over the channels, and shows a banner saying so. Your channels were already set up, so they just resume, no reconnecting. The daemon stays down until you start it again (opencrabs service start, or relaunch opencrabs daemon).

On a box where the daemon usually runs, the everyday flow is: open opencrabs when you want to sit down with it; close the TUI and opencrabs service start when you want it headless again.

Auto-start on boot

• Daemon — use the service installer (opencrabs service install); it wires up systemd (Linux) / launchd (macOS) to start on boot and restart on crash. This is the recommended always-on setup.
• TUI — to have the terminal UI open automatically on login, use a terminal/desktop autostart, not the service installer:
  • Linux desktop: drop a .desktop file in ~/.config/autostart/ with Exec=x-terminal-emulator -e opencrabs.
  • macOS: System Settings > General > Login Items > add a .command script that runs opencrabs.
  • VPS over SSH: run inside tmux/screen and reattach. On a headless VPS you usually want the daemon, not the TUI.

Strongly recommended for everyday users. If you plan to use OpenCrabs daily, ask it to set itself up as a system service. Just say something like “set yourself up to start with my computer” or “remove the auto-start service”. The agent handles the launchd (macOS) or systemd (Linux) setup and removal for you automatically.

Keep the TUI running on a VPS (tmux)

If you want the full interactive TUI always available on a remote server (not the headless daemon), tmux is the way. Your session survives SSH disconnects, laptop sleep, and flaky connections.

1. Install tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Find where opencrabs is installed

which opencrabs

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

3. Start a named tmux session

tmux new -s opencrabs

4. Launch opencrabs inside it

opencrabs

5. Detach (leaves opencrabs running)

Press Ctrl+B, then D. You can now close SSH and opencrabs keeps running.

6. Reattach later

tmux attach -t opencrabs

That’s it. Come back from any machine, reattach, and pick up where you left off. If you only need channels (Telegram, Discord, Slack, WhatsApp) running headless without the TUI, the daemon is a better fit: opencrabs service install && opencrabs service start.

Health Endpoint

Add to config.toml to expose a health check:

[daemon]
health_port = 8080

Then GET http://localhost:8080/health returns 200 OK with JSON status. Useful for systemd watchdog, uptime monitors, or load balancers.

Service Management

Install OpenCrabs as a system service (launchd on macOS, systemd on Linux):

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

Profile-aware services

Each profile gets its own independent service:

# 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

Multiple profiles can run as simultaneous daemon services with full isolation.

OPENCRABS_PROFILE environment variable

Set OPENCRABS_PROFILE=hermes to select a profile without the -p flag. Useful for systemd services, cron jobs, and daemon mode.

Troubleshooting: daemon stays down

If opencrabs service status says stopped:

1. Did you open the TUI? Opening opencrabs deliberately shuts the daemon down so the interactive session can own the channels. The daemon stays down until you opencrabs service start again.
2. Old builds may still have Restart=on-failure instead of Restart=always. Re-generate the unit with opencrabs service install (then service start) to pick up the always-restart policy.
3. Config, keys, commands, and tools hot-reload at runtime. Editing config.toml or keys.toml never needs a daemon restart. If a change isn’t taking effect, check the logs for a ConfigWatcher: reloaded line rather than restarting.

Cron Management

# 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"

TUI Keyboard Shortcuts