Hermes CLI cheatsheet

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

On Windows, run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell. macOS and Windows also ship a desktop package; hermes desktop builds it from a CLI install.

See: Installation

hermes setup --portal   # Portal login, provider, Tool Gateway
hermes setup            # full reconfiguration wizard
hermes setup model      # one section at a time

Sections are model, terminal, gateway, tools, and agent. Returning users get the wizard with current values as defaults.

See: hermes setup

hermes                                     # interactive session
hermes chat -q "Summarize the latest PRs"  # seeds the first turn
hermes chat --oneshot -q "Summarize this repo"
hermes -c                                  # continue the last session
hermes --resume latest --in ./my-project

On a real TTY, -q submits the prompt literally and stays interactive. --oneshot answers and exits.

See: Running the CLI

Option	Description
-q, --query "..."	Seed the session with a prompt
--query-file PATH	Read the query from a file or stdin
--oneshot	Answer the query and exit
-m, --model <model>	Override the model for this run
--provider <name>	Force a provider
-t, --toolsets <csv>	Enable a set of toolsets
-Q, --quiet	Suppress banner and tool previews
--format stream-json	Emit JSONL events for a -q run
--image <path>	Attach a local image to one query
-w, --worktree	Start in an isolated git worktree
--safe-mode	Disable all customizations

--tui opens the newer TUI; --cli forces the classic prompt_toolkit REPL.

See: hermes chat

hermes -z "What's the capital of France?"  # → Paris.
answer=$(hermes -z "summarize this" < notes.txt)
hermes -z "review this diff" --usage-file usage.json

-z prints only the final answer. Use chat --oneshot -q when tool output should reach stdout too.

Code	-z	chat -q
0	Turn completed	Turn completed
1	Completed with no text	Failed or never ran
2	Failed or usage error	—
130	Interrupted	Interrupted

See: Scripted one-shot

hermes model   # provider wizard: keys, OAuth, endpoints
/model         # switch configured providers and models
hermes chat --model anthropic/claude-sonnet-4

hermes model adds providers; /model can only switch the ones already set up. Override per run with --model or --provider.

See: hermes model

hermes auth                             # interactive wizard
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth  # browser login
hermes auth list                        # show credential pools
hermes auth reset openrouter            # clear cooldowns

Subcommands: add, list, remove, reset, priority, refresh, status, and logout.

See: hermes auth

Subcommand	Description
run	Run the gateway in the foreground
ensure	Start or discover the runtime; prints JSON
start	Start the installed systemd/launchd service
stop	Stop the service or foreground process
restart	Restart the service
status	Show service status
list	List profiles and whether their gateway runs
install	Install a systemd or launchd service
uninstall	Remove the installed service
setup	Set up messaging platforms interactively

On WSL, prefer gateway run inside tmux; systemd support is unreliable there.

tmux new -s hermes 'hermes gateway run'

See: hermes gateway

Subcommand	Description
list	List recent sessions
browse	Pick, search, and resume a session
export <out>	Export sessions to JSONL
delete <id>	Delete one session
prune	Delete sessions matching filters
archive	Soft-hide sessions matching filters
rename <id> <title>	Set or change a session title
stats	Show session-store statistics
optimize	Merge FTS5 segments and VACUUM

prune defaults to sessions older than 90 days; run it with --dry-run first.

hermes sessions prune --dry-run
hermes sessions export sessions.jsonl

See: hermes sessions

Command	Description
/new [name]	Start a fresh session
/clear	Clear the screen and start fresh
/resume [name]	Reopen a named session
/sessions	Browse and switch sessions
/compress [focus]	Summarize to free up context
/undo	Drop the last exchange
/rewind [N]	Edit an earlier prompt, or fork before it
/branch [name]	Copy the session to a new branch
/save <format>	Export as JSON, Markdown, or HTML

See: Session commands

Command	Description
/model	Pick a model or provider
/context	Show the context-window breakdown
/status	Show session details and a recap
/usage	Show tokens, cost, and account limits
/config	Show the current configuration

See: CLI slash commands

Command	Description
/queue <prompt>	Queue a prompt for the next turn
/steer <prompt>	Nudge the agent after the next tool call
/bg <prompt>	Run the prompt in a background session
/btw <question>	Ask a side question about the chat
/goal <text>	Set a goal that spans turns
/loop [interval] <prompt>	Re-run a prompt on a schedule
/heartbeat every <interval> <prompt>	Repeat a prompt while the session is idle

See: Session commands

Command	Description
/tools	List, enable, or disable tools
/toolsets	List available toolsets
/skills	Search, install, and manage skills
/memory	Review pending memory writes
/reload-mcp	Reload MCP servers and their tools

See: Tools and skills

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  deploy:
    type: exec
    command: scripts/deploy.sh
  inbox:
    type: alias
    target: /gmail unread

exec runs a shell command; alias points at another slash command.

See: Quick commands

Shortcut	Action
Enter	Send the message
Alt+Enter / Ctrl+J	Insert a newline
Ctrl+G	Edit the prompt in $EDITOR
Ctrl+S	Stash the draft; press again to restore
Ctrl+C	Clear the draft, then interrupt
Ctrl+T / F6	Open the live work monitor
Tab	Autocomplete; queue while busy
Ctrl+D	Exit; a running turn keeps going

See: Keybindings

> !git status
> !pytest -x tests/hermes_cli

! runs on your own machine and skips the model. A pasted block shows a one-line preview.

See: Shell mode

hermes config get model.default
hermes config set model.default claude-sonnet-4
hermes config check
hermes config migrate

Dotted keys edit config.yaml; UPPER_SNAKE names are written to .env. hermes config path and env-path print each file.

See: hermes config

hermes profile list
hermes profile create work --clone
hermes profile use work
hermes -p work chat -q "Hello from work"

Each profile has its own config, sessions, skills, and home. -p overrides the sticky default for one command.

See: hermes profile

Setting	Effect
HERMES_HOME	Select the user data directory
HERMES_TUI=1	Launch the TUI; same as --tui
HERMES_INFERENCE_MODEL	Model override for -z runs
--ignore-user-config	Skip config.yaml; .env still loads
--ignore-rules	Skip AGENTS.md, memory, and skills
--safe-mode	Disable all customizations

See: Configuration

hermes -z "summarize the failing test" --usage-file usage.json
hermes chat -q "review this diff" --format stream-json
hermes chat --safe-mode --model gpt-4.1 -q "Config bug?"

stream-json emits one JSON event per line. --safe-mode ignores your setup, so a broken config cannot block the run.

See: Scripted one-shot

hermes -w                     # session in a worktree
hermes -w -z "Fix issue #123" # one-shot in a worktree
/worktree new my-experiment   # mid-session worktree

Exiting an interactive session asks whether to keep or archive a dirty tree. One-shot runs keep it for the stale sweep; hermes worktree restore brings an archive back.

See: Git worktrees

hermes gateway setup
hermes send --to telegram "deploy finished"
echo "RAM 92%" | hermes send --to telegram:-1001234567890

/handoff telegram moves a live session into a chat thread; hermes send posts without an agent turn.

See: hermes send