# 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

```bash
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)

```bash
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.