✦
Hermes Agent
Open navigation menu

How-To Guide

Hermes Agent CLI Commands: Complete Guide

Use the current Hermes Agent CLI for chat, models, config, profiles, skills, MCP, gateways, sessions, cron jobs, diagnostics, and safe updates.

Quick answer

Start with hermes --version, hermes doctor, and hermes chat -q "Reply with exactly: ok". Use hermes for interactive chat; hermes model, config, profile, skills, tools, mcp, sessions, gateway, and cron for administration; and slash commands such as /model, /compress, /new, and /help inside a session. Verify changes in the real workflow, and do not copy obsolete commands such as hermes start, hermes logs, or hermes memory search from old guides.

The Hermes Agent CLI is the canonical control surface for interactive chat, one-shot automation, model selection, profiles, skills, MCP servers, gateways, sessions, cron jobs, memory, diagnostics, and updates. This guide replaces obsolete command examples with the current command tree and shows the verification step that matters after each change. Use the installation guide for first setup, the dashboard guide for private browser-based monitoring, and FlyHermes pricing when you want the outcome without maintaining the CLI host, gateway, or provider stack.

Deploy Hermes faster with FlyHermes

Managed cloud · API costs included · Skill library · Cancel anytime

Before you start:

  • ☑Hermes Agent installed from the official installer or an intentional source checkout
  • ☑A terminal where hermes --version resolves the expected binary
  • ☑One configured model provider or OAuth login for chat smoke tests

Steps

  1. 1

    Verify the installed CLI before configuring anything

    Run hermes --version, hermes doctor, and hermes status --all. Use hermes config path and hermes config env-path to confirm which profile's configuration and secret file the current command will read.

  2. 2

    Start interactive chat or run one command

    Run hermes or hermes chat for the interactive terminal, and hermes chat -q "Reply with exactly: ok" for a non-interactive smoke test. Add --quiet for scripts, --model <model> for one run, or --provider <provider> when the route must be explicit.

  3. 3

    Resume, name, or isolate a session

    Use hermes --continue for the most recent session, hermes --resume <session> for a specific session, and hermes sessions list or hermes sessions browse to find older work. Use --worktree when a coding agent needs an isolated Git worktree. Inside chat, use /title, /compress, /new, and /resume; /compress reduces context while /new starts clean.

  4. 4

    Configure the model and inspect the active route

    Use hermes model for the provider/model picker, hermes login --provider nous or hermes login --provider openai-codex for supported OAuth routes, and hermes config set <key> <value> for an explicit setting. Run hermes config check after an update and hermes config migrate only when the check reports missing or outdated options.

  5. 5

    Manage skills, tools, MCP servers, and plugins

    Use hermes skills list, hermes skills search <query>, and hermes skills install <id> for skills; hermes tools list for toolsets; hermes mcp list and hermes mcp test <name> for MCP; and hermes plugins list for plugins. Tool changes require a new session, while a newly configured MCP server may need /reload-mcp or a process restart.

  6. 6

    Separate profiles and credential pools

    Use hermes profile list, hermes profile create <name>, and hermes -p <name> ... when projects need isolated config, secrets, memory, skills, sessions, or bots. Use hermes auth list and hermes auth add for authorized credential pools; a pool rotates credentials but does not merge subscriptions or billing entitlements.

  7. 7

    Operate gateways and scheduled jobs with proof

    Use hermes gateway status, hermes gateway start, and hermes gateway restart for messaging services. Use hermes cron list, hermes cron status, and hermes cron runs <job> for scheduled work. A connected gateway or completed cron row is only a checkpoint—send one real message or inspect the external artifact before declaring success.

  8. 8

    Inspect memory and session state without inventing commands

    Use hermes memory status to inspect the memory provider and hermes sessions stats to inspect the SQLite session store. Search historical conversations through session search in an active Hermes conversation, and keep durable facts in memory rather than treating full transcripts as memory.

  9. 9

    Update and troubleshoot safely

    Run hermes update --check before hermes update, then verify hermes doctor, hermes gateway status, and one real workflow. Read ~/.hermes/logs/agent.log, gateway.log, or errors.log directly when diagnosing services; there is no general hermes logs --level debug command in the current CLI.

Pro Tips

  • 💡Run hermes <command> --help before copying an old blog command; the CLI evolves quickly.
  • 💡Type /help or /commands inside a chat to inspect in-session commands rather than guessing.
  • 💡Use /compress, not /compact, when a long conversation needs context reduction.
  • 💡Use hermes --continue or hermes -c to resume recent work and hermes sessions browse when you need a specific older session.
  • 💡Use a separate profile when projects need different secrets, memories, skills, files, or bot tokens.
  • 💡After enabling a toolset, start a new session so the tool schema and prompt cache stay consistent.
  • 💡Use hermes doctor for dependency/config health; use the exact gateway, cron, MCP, or provider command for the failing subsystem.
  • 💡Keep secrets in the profile .env, never in chat prompts, shell history, screenshots, or committed config.

Troubleshooting

❌ `hermes` command not found

✅ Open a new shell or reload the correct shell profile, then inspect which hermes. On macOS also check ~/.local/bin is on PATH. Do not reinstall until you know whether the existing binary is merely outside the current PATH.

❌ A copied command returns unknown command or option

✅ Run hermes --help and hermes <command> --help. Commands such as hermes start, hermes stop, hermes logs, hermes config show, and hermes memory search appear in older pages but are not the current general CLI. Use hermes gateway start/stop, hermes config, session search, and direct log files instead.

❌ `hermes chat` hangs or fails before the first response

✅ Run hermes doctor, inspect /provider or hermes config, then try hermes chat -q "Reply with exactly: ok". If using Ollama, verify the model server separately. If a provider returns 401/402/429, fix authentication, credits, or rate limits before changing gateway settings.

❌ The CLI works but Telegram, Discord, or Slack does not

✅ Run the same profile with hermes -p <profile> chat -q "Reply with exactly: ok", then inspect hermes gateway status, platform allowlists, topic/thread routing, and ~/.hermes/logs/agent.log. Finish with one message in the exact destination.

❌ A config or tool change is ignored

✅ Use /new after tool/skill changes, /reload-mcp after MCP changes, and restart the gateway after service config or source-code changes. Long-running processes can keep stale modules and connections in memory.

❌ The CLI and dashboard show different versions or profiles

✅ Compare which hermes, hermes --version, hermes config path, the dashboard backend process, and HERMES_HOME. Restart the stale layer; do not delete profiles or sessions to fix version skew.

FAQ

What are the most useful Hermes Agent CLI commands?

Start with hermes, hermes chat -q, hermes doctor, hermes model, hermes config, hermes profile list, hermes skills list, hermes mcp list, hermes sessions list, hermes gateway status, and hermes cron list.

How do I resume a Hermes Agent session?

Use hermes --continue for the most recent session or hermes --resume <session> for a specific one. Use hermes sessions list or hermes sessions browse to find the session first.

What is the difference between Hermes CLI commands and slash commands?

CLI commands run from your shell and manage Hermes as an application. Slash commands such as /model, /compress, /new, and /tools run inside an active conversation and affect that session or supported gateway surface.

How do I see Hermes Agent logs?

Inspect files under ~/.hermes/logs/, especially agent.log, gateway.log, and errors.log. Use hermes gateway status, hermes cron runs, or hermes mcp test for subsystem-specific evidence. The current CLI does not provide a general hermes logs --level debug command.

Does the CLI share state with the gateway and Web UI?

They can share the same profile-scoped Hermes home, but verify the active profile and HERMES_HOME. A service launched under another profile or stale environment can legitimately show different config, sessions, memory, or version.

Should I use the CLI or Hermes Dashboard?

Use the CLI for setup, exact commands, automation, and low-level diagnosis. Use the self-hosted Dashboard for private configuration and monitoring. Use FlyHermes when you want managed browser/mobile access and uptime without maintaining the host and gateway.

How do I update Hermes Agent from the CLI?

Run hermes update --check, protect important state, then run hermes update. Follow with hermes config check, hermes doctor, hermes gateway status, and one real end-to-end workflow test.

Related setup and cost guides

Install Hermes Agent

Use the official installer, configure one provider, and prove the first CLI response.

Update Hermes Agent safely

Preview updates, protect state, repair partial dependency failures, and verify the real runtime.

Create Hermes Agent skills

Turn repeatable CLI workflows into focused, tested skills.

Schedule Hermes Agent cron jobs

Create, run, diagnose, and verify scheduled work from the CLI.

Hermes Agent profiles guide

Isolate config, secrets, memory, skills, sessions, and messaging bots.

Related Guides

install hermes agentupdate hermes agentcreate hermes skillsschedule tasks with hermeshermes agent profiles guide