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​

Top-level commands​

hermes chat​

hermes chat [options]

Common options:

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 model​

Interactive provider + model selector.

hermes model

Use this when you want to:

• switch default providers
• log into OAuth-backed providers during model selection
• pick from provider-specific model lists
• configure a custom/self-hosted endpoint
• save the new default into config

/model slash command (mid-session)​

Switch models without leaving a session:

/model                              # Show current model and available options
/model claude-sonnet-4              # Switch model (auto-detects provider)
/model zai:glm-5                    # Switch provider and model
/model custom:qwen-2.5              # Use model on your custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4  # Switch back to cloud

Provider and base URL changes are persisted to config.yaml automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.

hermes gateway​

hermes gateway <subcommand>

Subcommands:

hermes setup​

hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset]

Use the full wizard or jump into one section:

Options:

hermes whatsapp​

hermes whatsapp

Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing.

hermes login / hermes logout​

hermes login [--provider nous|openai-codex] [--portal-url ...] [--inference-url ...]
hermes logout [--provider nous|openai-codex]

login supports:

• Nous Portal OAuth/device flow
• OpenAI Codex OAuth/device flow

Useful options for login:

• --no-browser
• --timeout <seconds>
• --ca-bundle <pem>
• --insecure

hermes auth​

Manage credential pools for same-provider key rotation. See Credential Pools for full documentation.

hermes auth                                              # Interactive wizard
hermes auth list                                         # Show all pools
hermes auth list openrouter                              # Show specific provider
hermes auth add openrouter --api-key sk-or-v1-xxx        # Add API key
hermes auth add anthropic --type oauth                   # Add OAuth credential
hermes auth remove openrouter 2                          # Remove by index
hermes auth reset openrouter                             # Clear cooldowns

Subcommands: add, list, remove, reset. When called with no subcommand, launches the interactive management wizard.

hermes status​

hermes status [--all] [--deep]

hermes cron​

hermes cron <list|create|edit|pause|resume|run|remove|status|tick>

hermes webhook​

hermes webhook <subscribe|list|remove|test>

Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.

hermes webhook subscribe​

hermes webhook subscribe <name> [options]

Subscriptions persist to ~/.hermes/webhook_subscriptions.json and are hot-reloaded by the webhook adapter without a gateway restart.

hermes doctor​

hermes doctor [--fix]

hermes config​

hermes config <subcommand>

Subcommands:

hermes pairing​

hermes pairing <list|approve|revoke|clear-pending>

hermes skills​

hermes skills <subcommand>

Subcommands:

Common examples:

hermes skills browse
hermes skills browse --source official
hermes skills search react --source skills-sh
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect official/security/1password
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install official/migration/openclaw-migration
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check
hermes skills update
hermes skills config

Notes:

• --force can override non-dangerous policy blocks for third-party/community skills.
• --force does not override a dangerous scan verdict.
• --source skills-sh searches the public skills.sh directory.
• --source well-known lets you point Hermes at a site exposing /.well-known/skills/index.json.

hermes honcho​

hermes honcho <subcommand>

Subcommands:

hermes acp​

hermes acp

Starts Hermes as an ACP (Agent Client Protocol) stdio server for editor integration.

Related entrypoints:

hermes-acp
python -m acp_adapter

Install support first:

pip install -e '.[acp]'

See ACP Editor Integration and ACP Internals.

hermes mcp​

hermes mcp <subcommand>

Manage MCP (Model Context Protocol) server configurations and run Hermes as an MCP server.

See MCP Config Reference, Use MCP with Hermes, and MCP Server Mode.

hermes plugins​

hermes plugins [subcommand]

Manage Hermes Agent plugins. Running hermes plugins with no subcommand launches an interactive curses checklist to enable/disable installed plugins.

Disabled plugins are stored in config.yaml under plugins.disabled and skipped during loading.

See Plugins and Build a Hermes Plugin.

hermes tools​

hermes tools [--summary]

Without --summary, this launches the interactive per-platform tool configuration UI.

hermes sessions​

hermes sessions <subcommand>

Subcommands:

hermes insights​

hermes insights [--days N] [--source platform]

hermes claw​

hermes claw migrate [options]

Migrate your OpenClaw setup to Hermes. Reads from ~/.openclaw (or a custom path) and writes to ~/.hermes. Automatically detects legacy directory names (~/.clawdbot, ~/.moldbot) and config filenames (clawdbot.json, moldbot.json).

What gets migrated​

The migration covers 30+ categories across persona, memory, skills, model providers, messaging platforms, agent behavior, session policies, MCP servers, TTS, and more. Items are either directly imported into Hermes equivalents or archived for manual review.

Directly imported: SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills (4 source directories), default model, custom providers, MCP servers, messaging platform tokens and allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent defaults (reasoning effort, compression, human delay, timezone, sandbox), session reset policies, approval rules, TTS config, browser settings, tool settings, exec timeout, command allowlist, gateway config, and API keys from 3 sources.

Archived for manual review: Cron jobs, plugins, hooks/webhooks, memory backend (QMD), skills registry config, UI/identity, logging, multi-agent setup, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.

API key resolution checks three sources in priority order: config values → ~/.openclaw/.env → auth-profiles.json. All token fields handle plain strings, env templates (${VAR}), and SecretRef objects.

For the complete config key mapping, SecretRef handling details, and post-migration checklist, see the full migration guide.

Examples​

# Preview what would be migrated
hermes claw migrate --dry-run

# Full migration including API keys
hermes claw migrate --preset full

# Migrate user data only (no secrets), overwrite conflicts
hermes claw migrate --preset user-data --overwrite

# Migrate from a custom OpenClaw path
hermes claw migrate --source /home/user/old-openclaw

hermes profile​

hermes profile <subcommand>

Manage profiles — multiple isolated Hermes instances, each with its own config, sessions, skills, and home directory.

Examples:

hermes profile list
hermes profile create work --clone
hermes profile use work
hermes profile alias work --name h-work
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"

hermes completion​

hermes completion [bash|zsh]

Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Hermes commands, subcommands, and profile names.

Examples:

# Bash
hermes completion bash >> ~/.bashrc

# Zsh
hermes completion zsh >> ~/.zshrc

Maintenance commands​

See also​

• Slash Commands Reference
• CLI Interface
• Sessions
• Skills System
• Skins & Themes