The Complete Hermes CLI Cheatsheet: Manage Your Agent like a Pro

Every serious Hermes user ends up with the same pattern. You spend a few hours learning the tool, then realize you only ever type 10 commands. The rest is muscle memory. This article is not a man page. It is the cheatsheet I wish I had on day two, written for people who are past the install wizard and need to actually run this thing.

Start here: the three modes

Hermes runs in three distinct modes. Getting this right up front saves a lot of confusion later.

Interactive chat is what most people use day-to-day. You run hermes or hermes --tui and get a persistent conversation with full tool access. The TUI mode is the modern version with modal overlays and mouse support, but both share the same sessions and config.

Single query mode is for scripting and automation. hermes chat -q "check disk space on production" runs one prompt and exits. No session, no history, just a result.

Gateway mode is what makes Hermes a 24/7 agent. hermes gateway run starts a long-running service that connects to your messaging platforms. This is what you want running on a VPS.

hermes                  # Interactive chat
hermes --tui           # Modern TUI chat (recommended)
hermes chat -q "..."   # Single query, non-interactive
hermes gateway run     # Long-running messaging gateway

The first 10 minutes on a new server

You have installed Hermes on a fresh VPS. Here is what you actually do in the first 10 minutes.

hermes doctor

Always run doctor first. It checks that your API keys are set, dependencies are installed, and the config file is valid. It catches problems before they bite you mid-session.

hermes config set model anthropic/claude-sonnet-4

Pick your model. You can do this interactively with hermes model or set it directly. OpenRouter works well on a budget VPS since it aggregates dozens of providers. If you are running sensitive workloads, Anthropic direct is the cleanest path.

hermes config set terminal.backend docker

On a shared VPS, run the agent in Docker. It sandbox the terminal tool so a runaway rm -rf only touches a container filesystem. This is not paranoia. It is standard practice.

hermes gateway install

Install the gateway as a systemd service so it survives reboots. On a server, you want this running independently of your SSH session.

Configuration the right way

Hermes stores config in two files. ~/.hermes/config.yaml holds settings. ~/.hermes/.env holds secrets. The CLI handles this automatically when you use hermes config set, but knowing why there are two files prevents confusion later.

hermes config edit            # Open config.yaml in your $EDITOR
hermes config set key val     # Set a value
hermes config get KEY          # Read a value
hermes config check            # Validate your config file

The most common mistake is editing the config file while Hermes is running and expecting changes to apply immediately. Most settings require a new session or a gateway restart. Check the docs on what requires what, or just restart to be safe.

hermes config migrate

Run this after updating Hermes. It patches your config file to include any new options that were added in the update, without losing your existing values.

Tools and when to enable them

Toolsets are groups of capabilities. Most are off by default. The right set depends on your threat model and what you actually need the agent to do.

hermes tools                 # Interactive tool picker (curses UI)
hermes tools list            # Show every tool and whether it is enabled
hermes tools enable terminal  # Turn on shell access
hermes tools disable browser  # Turn off browser automation

The most common setup for a self-hosted VPS agent: terminal, file, web, memory, session_search, and cronjob. Skip browser unless you need web automation. Skip image_gen unless you have a GPU or a paid image generation API.

One gotcha: enabling or disabling tools does not take effect in the current session. You need a fresh session for the tool list to update. Type /new or restart the gateway.

MCP servers

MCP extends what Hermes can do by connecting to external tool servers. The practical difference between a toolset and an MCP server is scope. Toolset is built-in capabilities. MCP is your own or third-party integrations.

hermes mcp add github --command npx --arg -y --arg @modelcontextprotocol/server-github
hermes mcp list

You can also expose Hermes itself as an MCP server for other tools to connect to:

hermes mcp serve

This lets Claude Code or Codex connect to your Hermes instance and use its gateway channels.

Skills

Skills are reusable instruction documents that teach Hermes how to do specific tasks. Unlike tools, which are code, skills are knowledge. The agent reads the skill file when a task matches its description.

hermes skills list              # Show what is installed
hermes skills browse           # Browse the hub catalog
hermes skills search kubernetes # Find by keyword
hermes skills install k8s-deploy  # Install from the hub
hermes skills check            # See which ones have updates

The hub has skills for Kubernetes, GitHub workflows, database management, and more. Installing a skill does not make it active everywhere. The agent only loads a skill when a task calls for it. This keeps the context window clean.

You can write your own skills. A skill is a SKILL.md file with frontmatter and step-by-step instructions. The skill for this blog post workflow, for example, lives in ~/.hermes/skills/ and gets loaded automatically when I work on the InterServer content pipeline.

Gateway and messaging platforms

The gateway is what makes Hermes accessible from your phone. Without it, you SSH in to chat. With it, you message your agent on Telegram like any other contact.

hermes gateway run            # Start in foreground (for debugging)
hermes gateway install        # Install as systemd service
hermes gateway start          # Start the service
hermes gateway stop           # Stop the service
hermes gateway restart        # Restart after config changes
hermes gateway status         # Check if it is running

The first time you set up a platform, use the interactive wizard:

hermes gateway setup

It walks you through Telegram bot tokens, Discord webhooks, Slack app credentials, and the rest. Telegram is the fastest to get running. You need a bot token from @BotFather, which takes about three minutes.

Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin, API Server, Webhooks.

One mistake to avoid: leaving dmPolicy as open on a public-facing bot. Without pairing or allowlisting, anyone who finds your bot can use it and burn through your API credits. Set it to pairing on first setup.

Cron jobs

Cron jobs turn Hermes from a reactive tool into a proactive one. Instead of asking your agent to check something, it watches for you and alerts when things change.

hermes cron list
hermes cron create "every 30m" "Check if any Docker containers have stopped"
hermes cron create "0 9 * * *" "Send me a morning server health report" --deliver origin
hermes cron pause ID
hermes cron remove ID

The schedule format is flexible. 30m fires once after 30 minutes. every 2h fires regularly. Standard cron expressions work too: 0 9 * * * is 9 AM every day.

Delivery targets are where the output goes. origin sends it back to the chat where the cron was created. telegram sends it to your Telegram home channel. local saves it to ~/.hermes/cron/output/ without notifying you.

hermes cron create "every 5m" "Alert me if disk usage is over 85%" --deliver telegram

That one-liner is the first cron job most people set up. It runs silently in the background and only speaks up when something needs attention.

Sessions

Hermes stores every conversation in ~/.hermes/sessions/. Sessions are searchable and resumable.

hermes sessions list           # Show recent sessions
hermes sessions browse         # Interactive picker
hermes sessions rename ID "Friday deploy"
hermes sessions delete ID      # Remove one
hermes sessions prune --older-than 30  # Clean up old ones

To resume a session, you do not need the ID. The title or a fragment of the first message is enough:

hermes --continue "Friday deploy"

The session store can grow large over months of daily use. Running hermes sessions prune every few weeks keeps it manageable.

Profiles

Profiles are isolated Hermes environments. Each profile has its own config, sessions, skills, and memory. This matters when you want to keep work and personal contexts separate.

hermes profile list
hermes profile create work --clone default
hermes profile use work

On a shared VPS where multiple people run their own agent, profiles are essential. Each person gets a fully isolated environment without stepping on anyone else.

hermes profile export work --output ~/work-profile.tar.gz
hermes profile import ~/work-profile.tar.gz

Export and import make it easy to move a profile between machines or share a setup with someone else.

Slash commands in session

Once you are inside a chat, the commands change. These are the in-session shortcuts.

/new           # Fresh session
/clear         # Clear screen + new session
/rollback 3    # Restore filesystem to 3 checkpoints ago
/model gpt-4o  # Switch model mid-session
/yolo           # Bypass command approval (be careful)
/tools          # Manage toolsets interactively
/skill blog    # Load a specific skill into session
/save          # Save this conversation to a file

The most underused one is /rollback. When Hermes breaks something during a file edit, /rollback restores from a checkpoint. It does not undo the edit, but it puts the files back to how they were before the bad edit. Checkpoints are enabled with hermes chat --checkpoints.

/approve       # Approve a pending command (gateway mode)
/deny           # Deny a pending command
/restart        # Restart the gateway
/platforms      # See which platforms are connected

When Hermes is running as a gateway and encounters a destructive command, it stops and waits. You approve or deny from the same chat. This is the human-in-the-loop safety net for autonomous operation.

Pairing and access control

When the gateway is running, anyone who messages your bot can potentially use it. Pairing is the gatekeeper.

hermes pairing list
hermes pairing approve telegram CODE
hermes pairing revoke telegram USER_ID

When someone new messages your Telegram bot, they get a pairing code. You approve it with the code and channel name. This is how you control access without pre-sharing user IDs.

The daily command set

Most days you will only run a handful of these:

hermes                  # Start chatting
hermes --continue        # Resume last session
hermes gateway status    # Is the bot running?
hermes gateway restart  # After config changes
hermes cron list        # Check scheduled jobs
hermes tools list       # Verify tools are configured
hermes skills check     # Any skill updates?
hermes doctor           # Something is broken

Everything else in the CLI is there for edge cases and automation. You will look up hermes profile import once, use it, and then forget the syntax. That is normal.

Ready to run a 24/7 AI agent on your VPS? InterServer VPS plans start at $6/month with full root access, 99.9% uptime, and everything you need to run Hermes Agent headless.

Related InterServer guide: If you want AI agents to connect directly to InterServer hosting tools, read InterServer MCP Server: Connect AI Agents to Your Hosting Account.