Hermes Agent CLI

Where the CLI Lives

The official installer (install.sh on Linux, macOS and WSL2, or install.ps1 on Windows) puts hermes on your PATH, and the Hermes Desktop installers set it up too. In the official Docker image the CLI is inside the container, so reach it with docker exec:

# Local install
hermes --help

# Docker install (container named "hermes")
docker exec -it hermes hermes --help

# Or, as a shell alias:
alias hermes='docker exec -it hermes hermes'

Core Commands

hermes --help lists everything, and there is a lot more: cron, kanban, profiles, sessions, backups, plugins and insights all have their own subcommands.

Talk to Hermes From Your Terminal

A bare hermes opens an interactive chat. To ask one question and get a clean answer back, use -z, which prints only the final reply:

hermes -z "What time is it in Tokyo right now?"

# Or answer one query and exit, with the normal output
hermes chat --oneshot -q "Summarize the latest PRs"

For a richer interactive session — model picker, session switcher, live view of subagents — use the TUI:

hermes --tui

# Or in Docker:
docker exec -it hermes hermes --tui

The TUI is the same agent your Telegram users talk to: same memory, same skills, same sessions. It is the easiest way to see what the bot will do before real users hit it. For how it compares with the desktop app and the web dashboard, see Hermes Agent GUI options.

Connect Messaging Platforms

Telegram, Discord, Slack and the other platforms are handled by the gateway. The interactive wizard asks for each platform's token and settings:

# 1. Configure platforms interactively
hermes gateway setup

# 2. Run the gateway in the foreground (recommended for Docker and WSL)
hermes gateway run

# ...or install it as a background service and start it
hermes gateway install
hermes gateway start

# 3. Approve a user who messaged the bot for a pairing code
hermes pairing list
hermes pairing approve telegram ABC123

Tokens can also be set directly: hermes config set TELEGRAM_BOT_TOKEN ... writes to ~/.hermes/.env, because upper-case names go to the env file and dotted names go to config.yaml. Restart the gateway afterwards with hermes gateway restart. Platform-specific steps are in Telegram setup, Discord setup and WhatsApp setup.

Skills, Plugins and MCP

# Skills
hermes skills search react
hermes skills install <skill>
hermes skills list

# MCP servers
hermes mcp                  # interactive catalog picker
hermes mcp add <name> --url https://example.com/mcp
hermes mcp test <name>

# Plugins
hermes plugins list
hermes plugins install <identifier>

See the Hermes skills guide and Hermes + MCP for more.

Model Management

hermes model is the full provider wizard: it adds providers, runs OAuth logins (Nous Portal, Anthropic, Codex, Copilot), takes API keys and sets the default model. Run it from your shell, not inside a chat. Inside a chat, the /model slash command only switches between providers you have already set up.

# Full provider and model setup
hermes model

# Read or change the default directly
hermes config get model.default
hermes config set model.default <model-id>

# Override the model for a single run
hermes chat -m <model-id> -q "Quick question"

Common CLI Recipes

Follow the logs while debugging

hermes logs -f                         # agent.log, live
hermes logs gateway -n 100             # last 100 gateway lines
hermes logs --level WARNING --since 1h # warnings and errors, last hour

One-shot ask from a shell script

ANSWER=$(hermes -z "Summarize the latest AI news in 3 bullets")
echo "$ANSWER"

Post a message from cron or CI

# No agent, no LLM: reuses the gateway's configured credentials
hermes send --to telegram "Nightly backup finished"

Check what is broken

hermes status --deep
hermes doctor

Hermes CLI on Managed Hosting

On managed Hermes hosting there is nothing to install. Each bot on your dashboard has a Terminal button that opens a shell inside that bot's own container, with hermes already on the PATH. Chat, -z, config, logs, pairing, skills, MCP and status commands all work there. Leave installing, updating and restarting to the dashboard: the bot runs in a managed container, so hermes update and hermes gateway install are not the way to manage it. The same card also opens the Hermes web dashboard if you would rather click than type.

Troubleshooting

• hermes not found. Open a new terminal so your shell picks up the PATH change from the installer, or use the docker exec form for a Docker install.
• A new provider does not show up in /model. In-chat /model cannot add providers. Exit the session and run hermes model.
• The gateway keeps dropping on WSL. Use hermes gateway run (inside tmux for persistence) instead of hermes gateway start; WSL's systemd support is unreliable.
• A token change did nothing. The gateway reads platform credentials when it starts. Run hermes gateway restart.
• Permission denied on Docker exec. Add your user to the docker group: sudo usermod -aG docker $USER, then log out and back in.

Skip the CLI — Use the Dashboard

Related Guides

• Install Hermes Agent
• Hermes Agent GUI options
• Hermes Agent Docker Guide
• Hermes on Telegram
• Hermes Skills
• Hermes + MCP