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.
One command — hermes setup --portal — and you're ready to hermes chat. See Nous Portal.
Hermes also ships a modern TUI with modal overlays, mouse selection, and non-blocking input. Launch it with hermes --tui — see the TUI guide.
Running the CLI
# Start an interactive session (default)
hermes
# Single query mode (non-interactive)
hermes chat -q "Hello"
# Single query from a file or stdin — nothing is shell-interpreted, so
# arbitrary text (quotes, $(...), backticks) arrives verbatim
hermes chat --query-file prompt.txt
hermes chat --query-file - < prompt.txt
# 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.
Interface Layout
The Hermes CLI banner, conversation stream, and fixed input prompt rendered as a stable docs figure instead of fragile text art.
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
| Element | Description |
|---|---|
| Model name | Current model (truncated if longer than 26 chars) |
| Token count | Context tokens used / max context window |
| Context bar | Visual fill indicator with color-coded thresholds |
| Cost | Estimated session cost (or n/a for unknown/zero-priced models) |
| 🗜️ N | Context compression count — how many times the running session has been auto-compressed. Appears once the first compression fires. |
| ▶ N | Active background tasks — how many /background prompts are still running in the current session. Appears whenever at least one task is in flight. |
| Duration | Elapsed session time |
| Session title | Once the session has a title, it appears as a gold badge pinned to the far-right edge. Long titles truncate before displacing the essential model and context fields. |
| ⚠ YOLO | YOLO mode warning — shown whenever HERMES_YOLO_MODE is on (either hermes --yolo at launch or /yolo toggled mid-session). Mirrors the banner-line warning so you can't forget you're in auto-approve mode. |
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:
| Color | Threshold | Meaning |
|---|---|---|
| Green | < 50% | Plenty of room |
| Yellow | 50–80% | Getting full |
| Orange | 80–95% | Approaching limit |
| Red | ≥ 95% | Near overflow — consider /compress |
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.
Keybindings
| Key | Action |
|---|---|
Enter | Send message |
Alt+Enter, Ctrl+J, or Shift+Enter | New line (multi-line input). Shift+Enter requires a terminal that distinguishes it from Enter — see below. On Windows Terminal, Alt+Enter is captured by the terminal (fullscreen toggle); use Ctrl+Enter or Ctrl+J instead. |
Alt+V | Paste an image from the clipboard when supported by the terminal |
Ctrl+V | Paste text and opportunistically attach clipboard images |
Ctrl+B | Start/stop voice recording when voice mode is enabled (voice.record_key, default: ctrl+b) |
Ctrl+G | Open the current input buffer in $EDITOR (vim/nvim/nano/VS Code/etc.). Save and quit to send the edited text as the next prompt — ideal for long, multi-paragraph prompts. |
Ctrl+X Ctrl+E | Emacs-style alternate binding for the external editor (same behavior as Ctrl+G). |
Ctrl+S | Stash the prompt. Parks the current draft and clears the composer so you can send something else first. Press Ctrl+S again on an empty composer to bring the draft back (cursor at the end, attached images restored). Repeated presses build a stack rather than overwriting, so an earlier draft is never silently lost — with two or more stashed, Ctrl+S opens a browse panel (↑/↓ to navigate, Enter to restore, D to discard, Esc or Ctrl+S to close). A 📌 N badge in the status bar shows how many drafts are parked. Multi-line drafts round-trip exactly, including blank lines. The stash lives in memory for the session only — nothing is written to disk, since drafts often contain secrets. |
Ctrl+C | Interrupt agent (double-press within 2s to force exit) |
Ctrl+D | Exit |
Ctrl+Z | Suspend Hermes to background (Unix only). Run fg in the shell to resume. |
Tab | Accept auto-suggestion (ghost text) or autocomplete slash commands |
!<command> | Shell mode — run a shell command yourself without spending a model turn (e.g. !git status, !pytest -x). See below. |
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
terminaltool runs. Uses the session working directory, so!pwdmatches 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'sterminaltool 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.
Slash Commands
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:
| Command | Description |
|---|---|
/help | Show command help |
/model | Show or change the current model |
/tools | List currently available tools |
/skills browse | Browse the skills hub and official optional skills |
/background <prompt> | Run a prompt in a separate background session |
/skin | Show or switch the active CLI skin |
/voice on | Enable CLI voice mode (press Ctrl+B to record) |
/voice tts | Toggle spoken playback for Hermes replies |
/reasoning high | Increase reasoning effort |
/title My Session | Name the current session |
/status | Show session info — model/profile/tokens/duration — followed by a local Session recap block (recent turn counts, top tools used, files touched, latest user prompt + assistant reply). Pure local compute; no LLM call. |
/context [all] | Visual context-usage breakdown — glyph block grid + per-category token table (system prompt / tools / skills / memory / conversation / free space). /context all adds per-skill and per-toolset costs. |
/sessions | Open an interactive session picker right inside the classic CLI (same surface the TUI uses). Type to filter, arrow keys to navigate, Enter to resume. |
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.
Commands are case-insensitive — /HELP works the same as /help. Installed skills also become slash commands automatically.
Quick Commands
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.
Preloading Skills at Launch
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.
Skill Slash Commands
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
Personalities
Set a predefined personality to change the agent's tone:
/personality pirate
/personality kawaii