Interactive vs Single-Query: Two Workflow Shapes

+15 Mana ✨
Hermes CLI Commands: Single-Query Mode(DOCUMENTATION)

Introduction

Hermes supports two fundamentally different ways of being run. Interactive is what you get when you type hermes, an open-ended back-and-forth session. Single-query is what you get when you run hermes -z "...", one input, one final answer, nothing else printed. Knowing when each one beats the other is the difference between using Hermes and building with it.

Key Concepts

  • Interactive mode: A session you join and leave. Multi-turn, exploratory, conversational.
  • Single-query mode (-z): A scripted call. One prompt in, one final response on stdout.
  • Quiet output: -z strips banners, status bars, and tool chatter so output is pipeable.

Real World Context

A developer tweaking a function uses interactive mode, they are going to bounce ideas, look at multiple drafts, change direction. A script that needs to summarize a daily log file uses -z: the script does not want a TUI, it wants a string. The same agent, the same provider, the same skills, but completely different surfaces because the caller is different.

Deep Dive

Two shapes side by side

bash
# Interactive, you are the caller
hermes
> "help me refactor this controller..."

# Single-query, a script is the caller
hermes -z "summarize the diff in HEAD~1..HEAD" > /tmp/digest.md

When single-query wins

  • In automation: cron jobs, hooks, CI steps that need an answer to compose the next step.
  • In pipes: anywhere stdout needs to feed another command without parsing prompts.
  • In hot paths: short, well-specified tasks where any interaction is overhead.

When interactive wins

  • Open-ended work: "I'm not sure what shape the answer takes yet."
  • Iteration: changing course based on the previous response.
  • Pairing: humans-in-the-loop on creative or architectural decisions.

The hidden third option

You can mix both. A script can call hermes -z to get a structured plan, then a human jumps into hermes --continue to refine it interactively, same session, two callers.

Common Pitfalls

  1. Reaching for interactive when -z would do, If you find yourself typing the same prompt every morning, that is a -z candidate.
  2. Trying to script around interactive output, Do not expect your way through a TUI. -z exists for exactly this reason.

Best Practices

  1. Default to interactive for thinking, -z for shipping, Interactive when you are exploring, -z when the prompt is fixed.
  2. Use -z in hooks and cron, Quiet output is a feature: it composes with the rest of the shell.

Summary

  • Interactive sessions are open-ended; single-query (-z) is one-shot.
  • -z outputs only the final answer, perfect for pipes and scripts.
  • Match the mode to the caller: humans get interactive, scripts get -z.
  • The two modes share the same agent, switching surfaces costs nothing.

Code Examples

bash
# Daily log digest, fully scripted, no TUI, no prompt parsing, just a string
digest=$(hermes -z "Summarize the last 24h of /var/log/app.log into 5 bullets")
echo "$digest" | mail -s "Daily digest" team@example.com

# A human picks up the same agent for follow-up
hermes --continue   # opens the most recent session, fully interactive
✓ Completed