Sókrates Wiki

Hermes CLI

3 min read

Hermes CLI

Summary

The Hermes CLI is the primary command-line interface for interacting with and managing the Hermes Agent. It provides interactive chat sessions, model/provider configuration, messaging gateway management, skill preloading, background task delegation, and system diagnostics — all backed by persistent SQLite session state.

Details

Core Interaction

The hermes chat command is the central feature. It supports interactive terminal sessions and one-shot queries via -q. Key flags:

  • -m / --model: Override the default model for a session
  • -t / --toolsets: Enable specific tool groups (e.g., "web,terminal,skills")
  • -s / --skills: Preload skills (e.g., hermes chat -s github-pr-workflow -s github-auth)
  • -w / --worktree: Operate in an isolated git worktree for safe parallel execution
  • -c / --continue: Resume the most recent CLI session
  • -r / --resume <session_id>: Jump back into a specific historical session
  • --yolo: Execute commands without manual approval prompts

Single-query mode is useful for automation: hermes chat -s github-pr-workflow -q "open a draft PR".

Session Persistence

Hermes maintains state in a SQLite database at ~/.hermes/state.db, storing session metadata (IDs, titles, timestamps, token usage), full message history, and lineage data for compressed or resumed sessions. Users can name sessions with /title <Name> or hermes sessions rename, and list history with hermes sessions list. Resumed sessions show a “Previous Conversation” recap panel.

Slash Commands and Keybindings

Typing / triggers autocomplete for system-level control:

  • Built-in: /help, /model (change LLM mid-session), /tools, /voice on/off, /reasoning high/low
  • Skills: Any skill in ~/.hermes/skills/ auto-registers as a slash command
  • Quick Commands: Shell commands defined in config, executed without LLM invocation

Keybindings:

  • Alt+Enter / Ctrl+J: Multi-line input (or backslash continuation)
  • Ctrl+C: Interrupt (double-press within 2s to force exit)
  • Ctrl+Z: Suspend to background (Unix), resume with fg
  • Ctrl+B: Toggle voice recording (configurable via voice.record_key)

Background Sessions

/background <prompt> delegates tasks to isolated agent sessions running in separate daemon threads. The foreground CLI stays interactive. Results display in a dedicated panel on completion, with optional display.bell_on_complete audible alert.

Model and Provider Management

hermes model provides an interactive selector. Supported backends: Anthropic, OpenRouter, OpenAI, HuggingFace, Zai, Kimi, Minimax, and custom/local endpoints. Mid-session switching via /model <name> persists changes to config.yaml automatically.

Gateway and Profile Administration

hermes gateway manages messaging profiles (WhatsApp, Telegram, Slack) — create, delete, rename, export as .tar.gz. hermes profile switches between global configs (e.g., dev vs production).

Setup and Configuration

hermes setup runs an interactive wizard (sections: model, terminal, gateway, tools, agent) for new installations. hermes config supports viewing, editing, and migrating settings. CLI behavior is tuned via ~/.hermes/config.yaml — key params include display.tool_preview_length (default 80 chars).

Security and Diagnostics

  • hermes login / hermes logout: OAuth and device flows for Nous Portal, OpenAI Codex
  • hermes doctor: Diagnose config issues and dependency mismatches
  • hermes status: Current agent state, auth status, platform connectivity
  • hermes insights: Token usage, costs, activity analytics
  • hermes auth: Manage credential pools

Integration

  • hermes mcp: Model Context Protocol integration
  • hermes plugins: Plugin management
  • hermes acp: Agent Control Protocol server for editor integrations

Graph View

Backlinks