CLI reference
The hermina CLI is the local administrative interface. It reads $HERMINA_HOME (default /root/hermina for source checkouts; /opt/hermina with the standard installer) and can directly access profiles, Docker, systemd, and Hermes.
Run hermina --help for the commands available in your installed version. With no arguments, hermina opens the TUI.
Onboarding and connection
| Command | Purpose |
|---|---|
hermina onboard | Guided server, model, agent, channel, and client setup |
hermina connect | Show server URL and current connection instructions |
hermina connect --qr | Show a client QR containing URL and API key |
hermina connect --code | Generate a short-lived pairing code |
hermina desktop | Open Electron/Web or print the URL on a headless server |
hermina tui | Open the interactive terminal UI |
Agent lifecycle
| Command | Purpose |
|---|---|
hermina list | List agents, runtime status, channel state, type, and port |
hermina status | Show general stack and agent status |
hermina add <name> <phone> | Create an agent profile and runtime |
hermina start <name> | Start a container or angel service |
hermina stop <name> | Stop the runtime |
hermina restart <name> | Restart the runtime |
hermina remove <name> | Remove an agent; use --keep-data=true to preserve profile data |
hermina build [name] | Rebuild an agent image or all required images |
hermina logs <name> | Show runtime logs; add --follow to stream |
hermina shell <name> <cmd> | Execute a command in the selected runtime |
hermina cat <name> <path> | Read a file from an agent profile/runtime |
Model, identity, and media
| Command | Purpose |
|---|---|
hermina model <name> | View or set provider, model, key, endpoint, and reasoning |
hermina media <name> | View or set vision, STT, and TTS |
hermina edit <name> | Edit the agent's SOUL.md |
hermina env <name> | Edit the agent's .env |
hermina personas | List persona categories and manage custom templates |
Run a configuration command without flags to show the current values and examples.
Channels and permissions
| Command | Purpose |
|---|---|
hermina channel <name> | View or set WhatsApp transport and Cloud settings |
hermina qr <name> | Show WhatsApp pairing guidance |
hermina bridge <name> | Check the linked-device bridge health |
hermina allowlist <name> | View or set allowed senders |
hermina groups <name> [on/off] | Control WhatsApp group replies |
hermina telegram-groups <name> [on/off] | Control Telegram mention-only group mode |
hermina matrix <name> | Configure Matrix and its room/user policy |
hermina commands <name> | Configure admin IDs and regular-user slash commands |
hermina sessions <name> | List, clear, or delete channel sessions |
Automation
| Command | Purpose |
|---|---|
hermina agent-cron <name> <action> | Manage cron jobs in one agent profile |
hermina host-cron <action> | Manage cron jobs in the host Hermes profile |
hermina queue enqueue <agent> <type> <payload> | Add a persistent task |
hermina queue list <agent> | List queued work |
hermina queue status <agent> [task-id] | Inspect recent or specific task state |
hermina queue cancel <agent> <task-id> | Cancel pending work |
hermina queue health <agent> | Check the internal queue service |
hermina queue logs <agent> | Show queue API and worker logs |
Management API service
| Command | Purpose |
|---|---|
hermina angels status | Check service and HTTP health |
hermina angels start/stop/restart | Control the management service |
hermina angels logs | Show service logs |
hermina angels key | List management keys locally |
hermina angels key generate | Add a new key |
hermina angels key delete <prefix> | Remove one key |
hermina angels qr <url> | Generate a client QR for a specific URL |
Boolean and structured values
The CLI is powered by Python Fire. For automation, prefer explicit values:
hermina add support 5511999999999 --start=true --lang=en
hermina sessions support --json-output=true
hermina remove support --keep-data=true --yes=true
Comma-separated lists are used for sender IDs and commands:
hermina allowlist support --numbers=5511888888888,5511777777777
hermina commands support --user-commands=help,whoami,status
Quote JSON payloads and values that contain spaces.
Scripting guidance
The CLI was designed primarily for human operation. Some commands prompt, some print formatted text, and not every error is exposed as structured JSON.
For reliable scripts:
- Pass confirmation and boolean flags explicitly.
- Use JSON output when a command offers it.
- Prefer the authenticated HTTP API for remote or concurrent automation.
- Do not mutate the same agent through the CLI and API concurrently.
- Validate the installed CLI help instead of assuming a command from newer documentation exists.