CLI Commands Reference
This page covers the terminal commands you run from your shell.
For in-chat slash commands, see Slash Commands Reference.
Global entrypoint
hermes [global-options] <command> [subcommand/options]
Global options
| Option | Description |
|---|---|
--version, -V | Show version and exit. |
--profile <name>, -p <name> | Select which Hermes profile to use for this invocation. Overrides the sticky default set by hermes profile use. |
--resume <session>, -r <session> | Resume a previous session by ID or title. The keyword latest resumes the most recent session (workspace-scoped, same lookup as -c). |
--continue [name], -c [name] | Resume the most recent session, or the most recent session matching a title. |
--in <dir> | Change into <dir> before starting or resuming. Scopes --resume latest / -c lookups to that directory's workspace and keeps the session there (skips the recorded-cwd restore). |
--worktree, -w | Start in an isolated git worktree for parallel-agent workflows. |
--yolo | Bypass dangerous-command approval prompts. |
--pass-session-id | Include the session ID in the agent's system prompt. |
--ignore-user-config | Ignore ~/.hermes/config.yaml and fall back to built-in defaults. Credentials in .env are still loaded. |
--ignore-rules | Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, memory, and preloaded skills. |
--tui | Launch the TUI instead of the classic CLI. Equivalent to HERMES_TUI=1. Always wins over display.interface. |
--cli | Force the classic prompt_toolkit REPL. Use this to override display.interface: tui for a single invocation. |
--dev | With --tui: run the TypeScript sources directly via tsx instead of the prebuilt bundle (for TUI contributors). |
Top-level commands
| Command | Purpose |
|---|---|
hermes chat | Interactive or one-shot chat with the agent. |
hermes model | Interactively choose the default provider and model. |
hermes moa | Configure named Mixture of Agents presets selectable from the model picker. |
hermes fallback | Manage fallback providers tried when the primary model errors. |
hermes gateway | Run or manage the messaging gateway service. |
hermes proxy | Local OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy. |
hermes egress | Outbound credential-injection firewall for remote terminal sandboxes (iron-proxy). Disabled by default. See Egress proxy. |
hermes lsp | Manage Language Server Protocol integration (semantic diagnostics for write_file/patch). |
hermes setup | Interactive setup wizard for all or part of the configuration. |
hermes whatsapp | Configure and pair the WhatsApp bridge. |
hermes whatsapp-cloud | Configure the official Meta WhatsApp Business Cloud API adapter (Business account + public webhook required). Distinct from hermes whatsapp (Baileys personal-account bridge). |
hermes slack | Slack helpers (currently: generate the app manifest with every command as a native slash). |
hermes auth | Manage credentials — add, list, remove, reset, status, logout. Handles OAuth flows for Codex/Nous/Anthropic. |
hermes login / logout | Deprecated — use hermes auth instead. |
hermes send | Send a one-shot message to a configured messaging platform (Telegram, Discord, Slack, Signal, SMS, …). Useful from shell scripts, cron jobs, CI hooks, and monitoring daemons — no agent loop, no LLM. |
hermes peer | Register peer Hermes gateways on other machines and DM their agents' canonical Bot Chats (hermes peer dm <peer>[/<agent>] "…"). The transport behind cross-machine bot-to-bot messaging. |
hermes secrets | Manage external secret sources (currently Bitwarden Secrets Manager) for pulling API keys at process startup instead of from ~/.hermes/.env. |
hermes migrate | Diagnose and (optionally) rewrite config.yaml to replace references to retired models or deprecated settings (e.g. migrate xai). |
hermes status | Show agent, auth, and platform status. |
hermes cron | Inspect and tick the cron scheduler. |
hermes kanban | Multi-profile collaboration board (tasks, links, dispatcher). |
hermes project | Manage named, multi-folder workspaces (projects). Anchors desktop session grouping and, when bound to a kanban board, gives tasks a deterministic worktree + branch convention. State is per-profile. |
hermes webhook | Manage dynamic webhook subscriptions for event-driven activation. |
hermes hooks | Inspect, approve, or remove shell-script hooks declared in config.yaml. |
hermes doctor | Diagnose config and dependency issues. |
hermes security audit | On-demand supply-chain audit (OSV.dev) for the venv, plugin requirements, and pinned MCP servers. |
hermes approvals | Approval-prompt tools — mine approval history into allowlist proposals. |
hermes dump | Copy-pasteable setup summary for support/debugging. |
hermes prompt-size | Show a byte breakdown of the system prompt + tool schemas (skills index, memory, profile). Runs offline. |
hermes debug | Debug tools — upload logs and system info for support. |
hermes backup | Back up Hermes home directory to a zip file. |
hermes checkpoints | Inspect / prune / clear ~/.hermes/checkpoints/ (the shadow store used by /rollback). Run with no args for a status overview. |
hermes import | Restore a Hermes backup from a zip file. |
hermes logs | View, tail, and filter agent/gateway/error log files. |
hermes config | Show, edit, migrate, and query configuration files. |
hermes skin | List, switch, and tweak display skins. |
hermes console | Open the safe Hermes command console. |
hermes pairing | Approve or revoke messaging pairing codes. |
hermes skills | Browse, install, publish, audit, and configure skills. |
hermes bundles | Group several skills under a single /<name> slash command. See Skill Bundles. |
hermes curator | Background skill maintenance — status, run, pause, pin. See Curator. |
hermes journey (aliases learning, memory-graph) | Timeline of learned skills + memories over time. |
hermes memory | Configure external memory provider. Plugin-specific subcommands (e.g. hermes honcho) register automatically when their provider is active. |
hermes acp | Run Hermes as an ACP server for editor integration. |
hermes mcp | Manage MCP server configurations and run Hermes as an MCP server. |
hermes plugins | Manage Hermes Agent plugins (install, enable, disable, remove). |
hermes portal | Nous Portal status, subscription link, and Tool Gateway routing. See Tool Gateway. |
hermes tools | Configure enabled tools per platform. |
hermes computer-use | Install or check the Computer Use (cua-driver) backend (macOS/Windows/Linux). |
hermes pets | Browse, install, and select petdex animated pets shown across the CLI, TUI, and desktop app. Subcommands: list, install, select, show, off, scale, remove, doctor. |
hermes sessions | Browse, export, prune, rename, and delete sessions. |
hermes insights | Show token/cost/activity analytics. |
hermes claw | OpenClaw migration helpers. |
hermes import-agent | Import a Claude Code (~/.claude) or Codex CLI (~/.codex) setup. |
hermes dashboard | Launch the web dashboard for managing config, API keys, and sessions. |
hermes serve | Start the Hermes backend server (headless; powers the desktop app and remote backends). |
hermes desktop (alias gui) | Build and launch the native Electron desktop app. |
hermes profile | Manage profiles — multiple isolated Hermes instances. |
hermes completion | Print shell completion scripts (bash/zsh/fish). |
hermes version | Show version information. |
hermes update | Pull latest code and reinstall dependencies. --check previews without installing; --backup takes a pre-pull HERMES_HOME snapshot. |
hermes uninstall | Remove Hermes from the system. |
hermes chat
hermes chat [options]
Common options:
| Option | Description |
|---|---|
-q, --query "..." | One-shot, non-interactive prompt. |
--query-file PATH | Read the one-shot prompt from a file (- = stdin). Nothing is shell-interpreted, so quotes, $(...), and backticks arrive verbatim — use this for programmatic or untrusted message bodies (Bot Mode teammate DMs use it). Mutually exclusive with -q. |
-m, --model <model> | Override the model for this run. |
-t, --toolsets <csv> | Enable a comma-separated set of toolsets. |
--provider <provider> | Force a provider: auto, openrouter, nous, openai-codex, copilot-acp, copilot, anthropic, gemini, huggingface, novita (aliases novita-ai, novitaai), openai-api, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, kilocode, xiaomi, arcee, gmi, upstage (alias solar), alibaba, alibaba-coding-plan (alias alibaba_coding), deepseek, nvidia, ollama-cloud, xai (alias grok), xai-oauth (alias grok-oauth), qwen-oauth, bedrock, opencode-zen, opencode-go, commandcode, commandcode-anthropic, ai-gateway, azure-foundry, lmstudio, stepfun, tencent-tokenhub (alias tencent, tokenhub). |
-s, --skills <name> | Preload one or more skills for the session (can be repeated or comma-separated). |
-v, --verbose | Verbose output. |
-Q, --quiet | Programmatic mode: suppress banner/spinner/tool previews. |
--image <path> | Attach a local image to a single query. |
--resume <session> / --continue [name] | Resume a session directly from chat. |
--worktree | Create an isolated git worktree for this run. |
--checkpoints | Enable filesystem checkpoints before destructive file changes. |
--yolo | Skip approval prompts. |
--pass-session-id | Pass the session ID into the system prompt. |
--ignore-user-config | Ignore ~/.hermes/config.yaml and use built-in defaults. Credentials in .env are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations. |
--ignore-rules | Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, persistent memory, and preloaded skills. Combine with --ignore-user-config for a fully isolated run. |
--safe-mode | Troubleshooting mode: disable ALL customizations — user config, rules/memory injection, plugins, shell hooks, and MCP servers (implies --ignore-user-config and --ignore-rules). Use to isolate whether a problem comes from your setup or from Hermes itself. |
--source <tag> | Session source tag for filtering (default: cli). Use tool for third-party integrations that should not appear in user session lists. |
--max-turns <N> | Maximum tool-calling iterations per conversation turn (default: 500, or agent.max_turns in config). |
Examples:
hermes
hermes chat -q "Summarize the latest PRs"
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills
hermes chat --quiet -q "Return only JSON"
hermes chat --worktree -q "Review this repo and open a PR"
hermes chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"
hermes chat --safe-mode -q "Is this bug mine or Hermes'?"
hermes -z <prompt> — scripted one-shot
For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), hermes -z is the purest one-shot entry point: single prompt in, final response text out, nothing else on stdout or stderr. No banner, no spinner, no tool previews, no Session: line — just the agent's final reply as plain text.
hermes -z "What's the capital of France?"
# → Paris.
# Parent scripts can cleanly capture the response:
answer=$(hermes -z "summarize this" < /path/to/file.txt)
Per-run overrides (no mutation to ~/.hermes/config.yaml):
| Flag | Equivalent env var | Purpose |
|---|---|---|
-m / --model <model> | HERMES_INFERENCE_MODEL | Override the model for this run |
--provider <provider> | (none) | Override the provider for this run |
--usage-file <path> | (none) | Write a JSON usage report after the run (see below) |
hermes -z "…" --provider openrouter --model openai/gpt-5.5
# or:
HERMES_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 hermes -z "…"
Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use hermes chat -q instead; -z is explicitly for "I only want the final answer".
--usage-file — JSON usage report for pipelines
hermes -z "…" --usage-file /path/report.json writes a machine-readable usage report after the run: estimated_cost_usd, input_tokens / output_tokens / cache_read_tokens / cache_write_tokens / reasoning_tokens / total_tokens, api_calls, model, provider, session_id, service_tier, and completed / failed flags. The report is written even when the run fails, so batch pipelines can always account for spend. It has no effect outside -z/--oneshot, and a broken usage write never masks the run's own outcome.