71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
|
# 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.
|