hermes-skills/ask-claude/references/hermes-headless-cli.md

Hermes Headless CLI — Local Peer Invocation

Verified 2026-06-30 against Hermes Agent installed at /home/n8n/.local/bin/hermes.

-z / --oneshot — Headless One-Shot Mode

hermes -z "your prompt here"

Prints ONLY the final response text to stdout. No banner, no spinner, no tool previews, no session_id line. Tools, memory, and skills are still loaded and used — you just don't see the intermediate output.

Verified: hermes -z "Reply with exactly: HEADLESS_TEST_OK" returned HEADLESS_TEST_OK with zero extra output.

Flags That Work With -z

Flag	Purpose	Example
-m MODEL	Model override	hermes -z "..." -m glm-5.2:cloud
--provider PROVIDER	Provider override	hermes -z "..." --provider custom:ollama
--resume SESSION	Resume a previous session by ID	hermes -z "..." --resume abc123
--continue [NAME]	Resume by name or most recent	hermes -z "..." --continue
-t TOOLSETS	Comma-separated toolsets	hermes -z "..." -t terminal,file
--safe-mode	No dangerous commands	hermes -z "..." --safe-mode
--yolo	Bypass approval prompts	hermes -z "..." --yolo
--pass-session-id	Include session_id in system prompt	hermes -z "..." --pass-session-id

Flags That Do NOT Exist

• -p / --profile — does NOT exist. Claude hallucinated this. The only way to target a specific profile is the sticky default (hermes profile use <name>).
• -Q / --quiet — only exists on hermes chat subcommand, NOT top-level. -z is already quiet by design.

hermes chat -q — Alternative One-Shot (Chat Subcommand)

hermes chat -q "your prompt" -Q

Also one-shot, but prints session info on exit. -Q suppresses some output. Use when you need the session_id for later --resume (since -z doesn't print it).

Session Persistence

• --resume <session_id> works with both -z and chat -q
• Session IDs are printed on exit from chat -q (not from -z)
• Sessions stored in ~/.hermes/state.db
• hermes sessions list shows all sessions

Comparison: hermes -z vs claude -p

Feature	hermes -z	claude -p
Output	Final response only	JSON envelope (session_id, result, cost, usage)
Session ID	Not printed	In JSON
Model override	-m	--model
Session resume	--resume	--resume
Max turns	Config-based	--max-turns
Cost tracking	None	total_cost_usd in JSON
Provider	Local Ollama (free)	Anthropic API (paid)

When to Use -z vs chat -q

• -z: When you just need the answer and don't care about session_id. Cleanest for one-shot queries.
• chat -q -Q: When you need the session_id for later --resume (multi-turn peer consultation). Parse the exit output for the session ID.

Pitfalls

• -z doesn't print session_id. If you need to resume later, use chat -q -Q instead and capture the session ID from the exit output.
• No -p/--profile flag. Target a profile by setting the sticky default first: hermes profile use <name>.
• -Q is chat-subcommand-only. Don't try hermes -z ... -Q — it'll error.
• -z still loads tools/memory/skills. It's not a stripped-down mode — the agent has full capabilities, just quiet output.