Getting started

Introduction

Hermes Agent is Nous Research's AI agent for the terminal. This reference covers the most commonly used commands, flags, and settings.

Install

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

Setup

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

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

See: hermes setup

First chat and resume

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

CLI reference

Chat

OptionDescription
-q, --query "..."Seed the session with a prompt
--query-file PATHRead the query from a file or stdin
--oneshotAnswer 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, --quietSuppress banner and tool previews
--format stream-jsonEmit JSONL events for a -q run
--image <path>Attach a local image to one query
--worktreeStart in an isolated git worktree
--safe-modeDisable all customizations

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

See: hermes chat

One-shot and scripting

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-zchat -q
0Turn completedTurn completed
1Completed with no textFailed or never ran
2Failed or usage error—
130InterruptedInterrupted

See: Scripted one-shot

Models

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

Credentials

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

Gateway

SubcommandDescription
runRun the gateway in the foreground
ensureStart or discover the runtime; prints JSON
startStart the installed systemd/launchd service
stopStop the service or foreground process
restartRestart the service
statusShow service status
listList profiles and whether their gateway runs
installInstall a systemd or launchd service
uninstallRemove the installed service
setupSet up messaging platforms interactively

See: hermes gateway

WSL

tmux new -s hermes 'hermes gateway run'

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

See: hermes gateway

Sessions

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

Subcommands

SubcommandDescription
listList recent sessions
browsePick, search, and resume a session
export <out>Export sessions to JSONL
delete <id>Delete one session
pruneDelete sessions matching filters
archiveSoft-hide sessions matching filters
rename <id> <title>Set or change a session title
statsShow session-store statistics
optimizeMerge FTS5 segments and VACUUM

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

See: hermes sessions

Slash commands

Session control

CommandDescription
/new [name]Start a fresh session
/clearClear the screen and start fresh
/resume [name]Reopen a named session
/sessionsBrowse and switch sessions
/compress [focus]Summarize to free up context
/undoDrop 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

Model, context, and status

CommandDescription
/modelPick a model or provider
/contextShow the context-window breakdown
/statusShow session details and a recap
/usageShow tokens, cost, and account limits
/configShow the current configuration

See: CLI slash commands

Prompts and automation

CommandDescription
/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

Tools and skills

CommandDescription
/toolsList, enable, or disable tools
/toolsetsList available toolsets
/skillsSearch, install, and manage skills
/memoryReview pending memory writes
/reload-mcpReload MCP servers and their tools

See: Tools and skills

Quick commands

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

Interactive mode

Keyboard

ShortcutAction
EnterSend the message
Alt+Enter / Ctrl+JInsert a newline
Ctrl+GEdit the prompt in $EDITOR
Ctrl+SStash the draft; press again to restore
Ctrl+CClear the draft, then interrupt
Ctrl+T / F6Open the live work monitor
TabAutocomplete; queue while busy
Ctrl+DExit; a running turn keeps going

See: Keybindings

Shell mode and multiline input

> !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

Configuration

Config

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

Profiles

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

Environment

SettingEffect
HERMES_HOMESelect the user data directory
HERMES_TUI=1Launch the TUI; same as --tui
HERMES_INFERENCE_MODELModel override for -z runs
--ignore-user-configSkip config.yaml; .env still loads
--ignore-rulesSkip AGENTS.md, memory, and skills
--safe-modeDisable all customizations

See: Configuration

Common workflows

Scripting and CI

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

Parallel agents

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

Messaging

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

Also see

0 Comments for this cheatsheet. Write yours!