Tutorial 5: Command Line Basics

Welcome back! In the last tutorial, we got Hermes installed and had our first chat. Now it’s time to level up. The real power of Hermes lives in your terminal. This tutorial walks you through the essential commands you’ll use every day.

Think of hermes as your command center. Every command follows the same pattern:

hermes [global-options] <command> [subcommand/options]
![Official CLI layout](/images/official/cli-layout.svg)

Your Daily Drivers

The first commands you’ll want to memorize are the ones for starting and resuming conversations:

hermes chat — Start an interactive chat session. This is your bread and butter.
hermes -r latest — Resume your most recent session. Picking up where you left off is as simple as that.
hermes -c "my project" — Resume the most recent session matching a title. Perfect when you’re juggling multiple projects.
hermes -r <session-id> — Resume a specific session by its ID.

Want to start fresh in a different folder? Use hermes --in <dir> to change directories before starting. It also scopes your session lookups to that folder’s workspace.

The Legacy `hermes-agent` Runner

The install also ships hermes-agent, a minimal runner that sends one query and exits: hermes-agent --query "summarize README.md" (or just hermes-agent "summarize README.md"). hermes-agent --help lists its options (--model, --base-url, --max-turns, --enabled-toolsets, --disabled-toolsets, --list-tools, --save-trajectories, …) and hermes-agent --version prints the version; neither starts the agent. Run it with no query and it prints the same help and exits. For anything else, use hermes (hermes -z <prompt> is the scripted one-shot).

Global Options Worth Knowing

Some options change how Hermes behaves entirely. Here are the ones you’ll actually use:

--yolo — Bypass dangerous-command approval prompts. Use with caution, but it’s great for trusted environments.
--profile <name> or -p <name> — Switch between different Hermes profiles. Great for separating work and personal setups.
--tui — Launch the fancy Terminal User Interface instead of the classic CLI. If you prefer a more visual experience, this is for you.
--cli — Force the classic prompt_toolkit REPL for a single run, even if your config defaults to the TUI.
--base-url <url> / --api-key <key> — Explicit OpenAI-compatible endpoint and launch-only key for --provider custom. The key is held in the running gateway’s memory for this session and never written to disk.
--worktree or -w — Start in an isolated git worktree. Perfect for running multiple agents in parallel without conflicts.
--ignore-rules — Skip auto-injection of AGENTS.md, SOUL.md, and other rule files. Useful when you want a clean slate.

Managing Your Setup

A few commands keep your configuration healthy:

hermes setup — Run the interactive setup wizard. Great for first-time configuration or adding new features.
hermes doctor — Diagnose config and dependency issues. Run this when something feels off. It exits with status 0 when the report lists no unresolved problems and 1 when at least one remains (including problems --fix could not repair), so a health gate or CI step can trust it as a check.
hermes migrate — Automatically rewrite your config.yaml to replace retired models or deprecated settings.
hermes config — Show, edit, and query your configuration files.
hermes status — See your agent, auth, and platform status at a glance. By default it prints a one-screen summary: your model, active provider, every provider with credentials (the same list the /model picker offers), gateway state, the messaging platforms the gateway would start, and scheduled jobs. No key values are printed. Add --full (or its alias --all) to print every section — API keys redacted, auth providers, terminal backend, sessions, and more. Add --deep to run deeper checks that may take longer; it implies --full. Any config values that differ from defaults are shown too, with credentials redacted (including a fallback_providers entry’s api_key and credentials hidden inside its base_url).
hermes usage — Show your account’s rate-limit windows without starting a session. Add --json if a script needs to read it.
hermes update — Update to the latest stable release (or the selected channel) and reinstall dependencies. --check previews without installing; --backup takes a pre-pull HERMES_HOME snapshot. A source checkout of the official repository defaults to the stable channel (the latest published vX.Y.Z GitHub release at its exact commit); forks and mirrors default to main. Run hermes update --set-channel main to follow every commit on main instead, or hermes update --set-channel stable to switch back. On the main channel, a checkout on another branch may be switched to the update branch before pulling, so commit branch work before updating when you want to keep it outside the update autostash flow. Every run writes a machine-readable receipt to ~/.hermes/logs/update_receipts/ in the root Hermes home (even from a sticky profile), and after the restart phase the updater verifies each live gateway’s running code against the updated checkout and prints a per-profile version matrix. A gateway still on pre-update code does not fail the update once the new code is in place: the update prints a ⚠ line with the exact restart command, exits 0, records a gateway_restart follow-up, and keeps the restart owed — every CLI start warns about it and the next hermes update retries it. If the in-process restart phase aborts while importing the freshly pulled tree, supervised gateway profiles are retried through a clean Python process; only restarts independently confirmed by systemd (systemctl --user is-active) are reported as verified, while a relaunch that merely exited 0 is recorded as relaunch_attempted and the restart stays owed. Manual gateways and serve/dashboard runtimes are never killed without a relaunch authority; they are recorded as skipped with a reason and remain in the incomplete-update report with the exact restart command.

Authentication and Credentials

Managing API keys and credentials is handled through:

hermes auth — Add, list, remove, and manage credentials. Handles OAuth flows for Codex, Nous, and Anthropic. Subcommands: add, list, remove, reset, priority, refresh, status, logout. When called with no subcommand, it launches the interactive management wizard. Spotify login has moved to the spotify catalog plugin’s hermes spotify login.
hermes secrets — Manage external secret sources like Bitwarden Secrets Manager.

Note: The old hermes login and hermes logout commands are now deprecated. Use hermes auth instead.

Beyond Chat

Hermes isn’t just about chatting. These commands extend its reach:

hermes send — Send a one-shot message to Telegram, Discord, Slack, or other platforms. No agent loop, no LLM. Perfect for shell scripts and cron jobs.
hermes cron — Inspect and tick the cron scheduler for scheduled tasks.
hermes pause / hermes resume — A global emergency stop. While paused, no new cron jobs, kanban dispatches, or gateway turns start. Interactive CLI, TUI and Desktop turns are gateway turns, so they are held too, and each surface shows “Hermes is paused” with the reason and “run hermes resume”. Turns already running finish; work already in flight keeps running.
hermes webapp — Open the Desktop workspace in a normal browser. The gateway serves it when webapp.enabled is true; the command builds the bundle when out of date, starts the gateway if it isn’t running, and opens a one-use sign-in link valid for 60 seconds.
hermes sessions refresh-prompts — Make continuing sessions rebuild their stored system prompt from the current SOUL.md, skills and context files on their next turn, keeping conversation history and session ids. --session ID limits it to one session; -p/--profile targets another profile. Each refreshed session pays one prompt-cache miss.
hermes import-agent / hermes claw — Import an OpenClaw, Claude Code, Codex CLI or Cursor setup (from the official agent-importers plugin: hermes plugins install agent-importers). Always previews first; API keys are never imported unless you pass --migrate-secrets for OpenClaw.
hermes webhook — Manage dynamic webhook subscriptions for event-driven activation.
hermes kanban — A multi-profile collaboration board for tasks and links.
hermes project — Manage named, multi-folder workspaces. Great for organizing complex projects.
hermes connectors — List, connect, rename and disconnect hosted connector accounts (apps such as Gmail reached through the Nous tool gateway). Needs a Nous Portal sign-in. One app can have several named accounts. Subcommands: list lists connectors and whether each is connected; accounts [app] [--all] lists accounts for one app or all of them (--all includes retired accounts); connect <app> [--alias NAME] [--reconnect [--force]] prints the link to connect an account and then waits until it is connected or the deadline passes (Ctrl-C stops waiting), where --alias names the account and a new name adds another account, and --reconnect repairs the named account and deletes nothing (on an account that is already connected it says so and does nothing unless --force is given); rename <app> <name-or-label> --to <new> renames an account, matching an unnamed account by its app label; and disconnect <app> [--alias NAME] [--yes] removes an account, asking to confirm unless you pass --yes. Rename needs a Nous Portal version that supports it; until then it reports “This Nous Portal cannot rename connector accounts yet.”
hermes mcp — Manage MCP server configurations. Running Hermes itself as an MCP server moved to the mcp-serve plugin (hermes plugins install mcp-serve, then hermes mcp-serve); hermes mcp serve prints that new spelling.
hermes codex-runtime — The scriptable version of /codex-runtime. Its migrate subcommand regenerates the Hermes-managed block in ~/.codex/config.toml for the selected profile; add --dry-run to preview or --json for machine-readable output.
hermes memory — Set up and manage external memory provider plugins. Bundled providers: retaindb and byterover; honcho, hindsight, supermemory, mem0, openviking and holographic come from the plugin catalog after hermes plugins install <name> (hermes update does this automatically for a provider already named in memory.provider). Only one external provider can be active at a time, and built-in memory (MEMORY.md/USER.md) is always active.

Maintenance and Debugging

When things go wrong (or you just want to keep things tidy):

hermes logs — View, tail, and filter log files. Pass a log_name to pick which one: agent (the default), errors, gateway, gui, desktop, update, handoff, or list to show the available files with their sizes. A line without its own timestamp, like a traceback frame or the rest of a multi-line message, is shown or hidden together with the timestamped line above it.
hermes backup — Back up your entire Hermes home directory to a zip file.
hermes import — Restore from a backup.
hermes checkpoints — Inspect or prune the shadow store used by /rollback.
hermes debug — Upload logs and system info for support. The report includes system info (OS, Python version, Hermes version), recent agent, gateway, GUI/dashboard, and desktop logs (512 KB limit per file), plus the update and Desktop update hand-off logs when present, and redacted API key status. By default uploads are redacted so secrets are not included — this covers the system dump (including config values such as fallback_providers entries and credentials in their URLs), the logs, and the gateway /debug report too.
hermes dump — Get a copy-pasteable setup summary for debugging.
hermes security audit — Run an on-demand supply-chain audit.

Pro Tips

Use hermes --version to check your current version before reporting issues.
Run hermes doctor after updating to catch configuration problems early.
Explore hermes model to interactively choose your default provider and model.
Check hermes prompt-size to see the byte breakdown of your system prompt — useful for optimizing context usage.
Add --format stream-json to a hermes chat -q "..." run when a script needs to consume progress as structured JSONL instead of scraping terminal output. A result event carries replay_gap: true when the run fell behind the gateway’s stream and re-attached, so its text events stopped early (text here is still the whole reply).
Pin your update channel with hermes update --set-channel main to persist the channel for this source installation without applying an update (stable and main are the valid source channels; bundled apps have a fixed build channel and refuse changes). Use --channel main to select it for a single invocation only.

That’s the command-line tour! You now know enough to navigate Hermes like a pro. In the next tutorial, we’ll dive into slash commands you can use inside your chat sessions. See you there!