CLI Interface

Hermes Agent's CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal.

# Start an interactive session (default)
hermes

# Single query mode (non-interactive)
hermes chat -q "Hello"

# With a specific model
hermes chat --model "anthropic/claude-sonnet-4"

# With a specific provider
hermes chat --provider nous        # Use Nous Portal
hermes chat --provider openrouter  # Force OpenRouter

# With specific toolsets
hermes chat --toolsets "web,terminal,skills"

# Start with one or more skills preloaded
hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -q "open a draft PR"

# Resume previous sessions
hermes --continue             # Resume the most recent CLI session (-c)
hermes --resume <session_id>  # Resume a specific session by ID (-r)
hermes --resume latest        # Resume the most recent session (same as -c)
hermes --resume latest --in ./dir  # Resume ./dir's latest session, staying in ./dir

# Verbose mode (debug output)
hermes chat --verbose

# Isolated git worktree (for running multiple agents in parallel)
hermes -w                         # Interactive mode in worktree
hermes -w -z "Fix issue #123"     # Single query in worktree

Plugin management

The hermes plugins commands manage native Hermes plugins and portable Agent Plugins v1 packages through the same opt-in workflow:

hermes plugins install owner/repository --no-enable
hermes plugins list
hermes plugins enable <plugin-name>
hermes plugins disable <plugin-name>
hermes plugins update <plugin-name>
hermes plugins remove <plugin-name>

Portable packages remain disabled until explicitly enabled. Hermes currently loads portable Agent Skills and stdio MCP entries. See the plugin developer guide for the exact supported subset and trust boundary.

<img className="docs-terminal-figure" src="/docs/img/docs/cli-layout.svg" alt="Stylized preview of the Hermes CLI layout showing the banner, conversation area, and fixed input prompt." /> <p className="docs-figure-caption">The Hermes CLI banner, conversation stream, and fixed input prompt rendered as a stable docs figure instead of fragile text art.</p>

The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.

Status Bar

A persistent status bar sits above the input area, updating in real time:

 ⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m

The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration, plus the YOLO badge when active) below 52.

Context color coding:

Use /usage for a detailed breakdown including per-category costs (input vs output tokens).

On the openai-codex provider, /usage also shows any banked usage-limit resets on your ChatGPT account ("You have N resets banked - use /usage reset to activate"). /usage reset redeems one banked reset, fully restoring your 5-hour and weekly limits. Hermes refuses to redeem while your limits aren't exhausted (a banked reset restores the full allowance, so spending it early wastes it) — pass /usage reset --force to redeem anyway.

Session Resume Display

When resuming a previous session (hermes -c or hermes --resume <id>), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of the conversation history. See Sessions — Conversation Recap on Resume for details and configuration.

Multiline paste preview. When you paste a multi-line block, the CLI echoes a compact single-line preview ([pasted: 47 lines, 1,842 chars — press Enter to send]) instead of dumping the whole payload into the scrollback. The full content is still what gets sent; this is just display polish.

! Shell Mode

Start a line with ! to run it as a shell command instead of sending it to the agent:

> !git status
> !ls -la
> !pytest -x tests/cli

• Zero cost. The model is never invoked — no API call, no tokens, no latency.
• Nothing enters the conversation. The command and its output are not added to history, so your context stays clean and the prompt cache is untouched.
• Runs where the agent's terminal tool runs. Uses the session working directory, so !pwd matches what the agent would see.
• Approvals still apply. A dangerous command (rm -rf, writes to ~/.hermes/config.yaml, etc.) goes through the same approval prompt the agent's terminal tool uses. ! is a cost/latency shortcut, not a security bypass.
• Non-zero exits are shown. A failing command prints ! exited <code> after its output.
• ! on its own prints a one-line usage reminder.

Shell mode is CLI-only. Gateway platforms (Discord, Telegram, Slack) and cron runs ignore it — those users already have their own shells.

Markdown stripping in final responses. The CLI strips the most verbose markdown fences and **bold** / *italic* wrappers from final agent replies so they render as readable terminal prose rather than raw source. Code blocks and lists are preserved. This does not affect gateway platforms or tool results — they keep their markdown for native rendering.

Type / to see the autocomplete dropdown. Hermes supports a large set of CLI slash commands, dynamic skill commands, and user-defined quick commands.

Common examples:

For the full built-in CLI and messaging lists, see Slash Commands Reference.

For setup, providers, silence tuning, and messaging/Discord voice usage, see Voice Mode.

You can define custom commands that run shell commands instantly without invoking the LLM. These work in both the CLI and messaging platforms (Telegram, Discord, etc.).

# ~/.hermes/config.yaml
quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  restart:
    type: alias
    target: /gateway restart

Then type /status, /gpu, or /restart in any chat. See the Configuration guide for more examples.

If you already know which skills you want active for the session, pass them at launch time:

hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -s github-auth

Hermes loads each named skill into the session prompt before the first turn. The same flag works in interactive mode and single-query mode.

Every installed skill in ~/.hermes/skills/ is automatically registered as a slash command. The skill name becomes the command:

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

Set a predefined personality to change the agent's tone:

/personality pirate
/personality kawaii
/personality concise

Built-in personalities include: helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype.

To go back to the default (no overlay), use /personality none — default and neutral work too.

You can also define custom personalities in ~/.hermes/config.yaml:

personalities:
  helpful: "You are a helpful, friendly AI assistant."
  kawaii: "You are a kawaii assistant! Use cute expressions..."
  pirate: "Arrr! Ye be talkin' to Captain Hermes..."
  # Add your own!

There are two ways to enter multi-line messages:

1. Alt+Enter, Ctrl+J, or Shift+Enter — inserts a new line
2. Backslash continuation — end a line with \ to continue:

❯ Write a function that:\
  1. Takes a list of numbers\
  2. Returns the sum

Ctrl+J and backslash continuation are enabled by default, matching Claude Code / Codex / OpenCode multiline shortcuts. On supported terminals such as iTerm2, Hermes also requests extended key reporting so Shift+Enter arrives as a distinct newline key. If your terminal sends LF for plain Enter and you need the legacy Ctrl+J-as-submit fallback, opt out:

# ~/.hermes/config.yaml
display:
  cli_multiline_shortcuts: false

Shift+Enter compatibility

Most terminals send the same byte sequence for Enter and Shift+Enter by default, so applications cannot distinguish them. Hermes recognises Shift+Enter only when the terminal sends a distinct sequence via the Kitty keyboard protocol ↗ or xterm's modifyOtherKeys mode.

Where the terminal cannot distinguish them, Alt+Enter and Ctrl+J continue to work by default. On Windows Terminal specifically, Alt+Enter is captured by the terminal (toggles fullscreen) and never reaches Hermes — use Ctrl+Enter (delivered as Ctrl+J) or Ctrl+J directly for a newline.

While the agent is working, you can send a correction without starting a new turn:

• Type a new message + Enter — redirects the active turn using your correction
• Ctrl+C — interrupt the current operation (press twice within 2s to force exit)
• Completed tool work and reasoning already shown stay in context
• A running tool reaches its safe boundary before the correction is applied

Busy Input Mode

The display.busy_input_mode config key controls what happens when you press Enter while the agent is working:

# ~/.hermes/config.yaml
display:
  busy_input_mode: "steer"   # or "queue" or "interrupt" (default)

"queue" mode prepares a separate follow-up turn. "steer" always waits for the next tool-result boundary. The default "interrupt" mode responds sooner during model generation while avoiding cancellation of a running tool. Use /stop when you want to cancel the turn and its foreground work. Unknown values fall back to "interrupt".

"steer" has two automatic fallbacks: if the agent hasn't started yet, or if images are attached, the message falls back to "queue" behavior so nothing is lost.

You can also change it inside the CLI:

/busy queue
/busy steer
/busy interrupt
/busy status

Suspending to Background

On Unix systems, press Ctrl+Z to suspend Hermes to the background — just like any terminal process. The shell prints a confirmation:

Hermes Agent has been suspended. Run `fg` to bring Hermes Agent back.

Type fg in your shell to resume the session exactly where you left off. This is not supported on Windows.

The CLI shows animated feedback as the agent works:

Thinking animation (during API calls):

  ◜ (｡•́︿•̀｡) pondering... (1.2s)
  ◠ (⊙_⊙) contemplating... (2.4s)
  ✧٩(ˊᗜˋ*)و✧ got it! (3.1s)

Tool execution feed:

  ┊ 💻 terminal `ls -la` (0.3s)
  ┊ 🔍 web_search (1.2s)
  ┊ 📄 web_extract (2.1s)

Cycle through display modes with /verbose: off → new → all → verbose. This command can also be enabled for messaging platforms — see configuration.

Tool Preview Length

The display.tool_preview_length config key controls the maximum number of characters shown in tool call preview lines (e.g. file paths, terminal commands). The default is 0, which means no limit — full paths and commands are shown.

# ~/.hermes/config.yaml
display:
  tool_preview_length: 80   # Truncate tool previews to 80 chars (0 = no limit)

This is useful on narrow terminals or when tool arguments contain very long file paths.

Resuming Sessions

When you exit a CLI session, a resume command is printed:

Resume this session with:
  hermes --resume 20260225_143052_a1b2c3

Session:        20260225_143052_a1b2c3
Duration:       12m 34s
Messages:       28 (5 user, 18 tool calls)

Resume options:

hermes --continue                          # Resume the most recent CLI session
hermes -c                                  # Short form
hermes -c "my project"                     # Resume a named session (latest in lineage)
hermes --resume 20260225_143052_a1b2c3     # Resume a specific session by ID
hermes --resume "refactoring auth"         # Resume by title
hermes --resume latest                     # Resume the most recent session (same as -c)
hermes --resume latest --in ./my-project   # Latest session for ./my-project's workspace
hermes -r 20260225_143052_a1b2c3           # Short form

Resuming restores the full conversation history from SQLite. The agent sees all previous messages, tool calls, and responses — just as if you never left.

Use /title My Session Name inside a chat to name the current session, or hermes sessions rename <id> <title> from the command line. Use hermes sessions list to browse past sessions.

Session Storage

CLI sessions are stored in Hermes's SQLite state database under ~/.hermes/state.db. The database keeps:

• session metadata (ID, title, timestamps, token counters)
• message history
• lineage across compressed/resumed sessions
• full-text search indexes used by session_search

Some messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store.

Context Compression

Long conversations are automatically summarized when approaching context limits:

# In ~/.hermes/config.yaml
compression:
  enabled: true
  threshold: 0.50    # Compress at 50% of context limit by default

# Summarization model configured under auxiliary:
auxiliary:
  compression:
    model: ""  # Leave empty to use the main chat model (default). Or pin a cheap fast model, e.g. "google/gemini-3-flash-preview".

When compression triggers, middle turns are summarized while the first 3 and last 20 turns are always preserved.

Run a prompt in a separate background session while continuing to use the CLI for other work:

/background Analyze the logs in /var/log and summarize any errors from today

Hermes immediately confirms the task and gives you back the prompt:

🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..."
   Task ID: bg_143022_a1b2c3

How It Works

Each /background prompt spawns a completely separate agent session in a daemon thread:

• Isolated conversation — the background agent has no knowledge of your current session's history. It receives only the prompt you provide.
• Same configuration — the background agent inherits your model, provider, toolsets, reasoning settings, and fallback model from the current session.
• Non-blocking — your foreground session stays fully interactive. You can chat, run commands, or even start more background tasks.
• Multiple tasks — you can run several background tasks simultaneously. Each gets a numbered ID.

Results

When a background task finishes, the result appears as a panel in your terminal:

╭─ ⚕ Hermes (background #1) ──────────────────────────────────╮
│ Found 3 errors in syslog from today:                         │
│ 1. OOM killer invoked at 03:22 — killed process nginx        │
│ 2. Disk I/O error on /dev/sda1 at 07:15                      │
│ 3. Failed SSH login attempts from 192.168.1.50 at 14:30      │
╰──────────────────────────────────────────────────────────────╯

If the task fails, you'll see an error notification instead. If display.bell_on_complete is enabled in your config, the terminal bell rings when the task finishes.

Use Cases

• Long-running research — "/background research the latest developments in quantum error correction" while you work on code
• File processing — "/background analyze all Python files in this repo and list any security issues" while you continue a conversation
• Parallel investigations — start multiple background tasks to explore different angles simultaneously

By default, the CLI runs in quiet mode which:

• Suppresses verbose logging from tools
• Enables kawaii-style animated feedback
• Keeps output clean and user-friendly

For debug output:

hermes chat --verbose