hermes-agent/website/docs/reference/cli-commands.md

sidebar_position, title, description

sidebar_position	title	description
1	CLI Commands Reference	Authoritative reference for Hermes terminal commands and command families

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

Option	Description
--version, -V	Show version and exit.
--resume <session>, -r <session>	Resume a previous session by ID or title.
--continue [name], -c [name]	Resume the most recent session, or the most recent session matching a title.
--worktree, -w	Start in an isolated git worktree for parallel-agent workflows.
--yolo	Bypass dangerous-command approval prompts.
--pass-session-id	Include the session ID in the agent's system prompt.

Top-level commands

Command	Purpose
hermes chat	Interactive or one-shot chat with the agent.
hermes model	Interactively choose the default provider and model.
hermes gateway	Run or manage the messaging gateway service.
hermes setup	Interactive setup wizard for all or part of the configuration.
hermes whatsapp	Configure and pair the WhatsApp bridge.
hermes login / logout	Authenticate with OAuth-backed providers.
hermes status	Show agent, auth, and platform status.
hermes cron	Inspect and tick the cron scheduler.
hermes webhook	Manage dynamic webhook subscriptions for event-driven activation.
hermes doctor	Diagnose config and dependency issues.
hermes config	Show, edit, migrate, and query configuration files.
hermes pairing	Approve or revoke messaging pairing codes.
hermes skills	Browse, install, publish, audit, and configure skills.
hermes honcho	Manage Honcho cross-session memory integration.
hermes acp	Run Hermes as an ACP server for editor integration.
hermes tools	Configure enabled tools per platform.
hermes sessions	Browse, export, prune, rename, and delete sessions.
hermes insights	Show token/cost/activity analytics.
hermes claw	OpenClaw migration helpers.
hermes version	Show version information.
hermes update	Pull latest code and reinstall dependencies.
hermes uninstall	Remove Hermes from the system.

hermes chat

hermes chat [options]

Common options:

Option	Description
-q, --query "..."	One-shot, non-interactive prompt.
-m, --model <model>	Override the model for this run.
-t, --toolsets <csv>	Enable a comma-separated set of toolsets.
--provider <provider>	Force a provider: auto, openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, alibaba, zai, kimi-coding, minimax, minimax-cn, kilocode.
-s, --skills <name>	Preload one or more skills for the session (can be repeated or comma-separated).
-v, --verbose	Verbose output.
-Q, --quiet	Programmatic mode: suppress banner/spinner/tool previews.
--resume <session> / --continue [name]	Resume a session directly from chat.
--worktree	Create an isolated git worktree for this run.
--checkpoints	Enable filesystem checkpoints before destructive file changes.
--yolo	Skip approval prompts.
--pass-session-id	Pass the session ID into the system prompt.

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:

Subcommand	Description
run	Run the gateway in the foreground.
start	Start the installed gateway service.
stop	Stop the service.
restart	Restart the service.
status	Show service status.
install	Install as a user service (systemd on Linux, launchd on macOS).
uninstall	Remove the installed service.
setup	Interactive messaging-platform setup.

hermes setup

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

Use the full wizard or jump into one section:

Section	Description
model	Provider and model setup.
terminal	Terminal backend and sandbox setup.
gateway	Messaging platform setup.
tools	Enable/disable tools per platform.
agent	Agent behavior settings.

Options:

Option	Description
--non-interactive	Use defaults / environment values without prompts.
--reset	Reset configuration to defaults before setup.

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 status

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

Option	Description
--all	Show all details in a shareable redacted format.
--deep	Run deeper checks that may take longer.

hermes cron

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

Subcommand	Description
list	Show scheduled jobs.
create / add	Create a scheduled job from a prompt, optionally attaching one or more skills via repeated --skill.
edit	Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports --clear-skills, --add-skill, and --remove-skill.
pause	Pause a job without deleting it.
resume	Resume a paused job and compute its next future run.
run	Trigger a job on the next scheduler tick.
remove	Delete a scheduled job.
status	Check whether the cron scheduler is running.
tick	Run due jobs once and exit.

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.

Subcommand	Description
subscribe / add	Create a webhook route. Returns the URL and HMAC secret to configure on your service.
list / ls	Show all agent-created subscriptions.
remove / rm	Delete a dynamic subscription. Static routes from config.yaml are not affected.
test	Send a test POST to verify a subscription is working.

hermes webhook subscribe

hermes webhook subscribe <name> [options]

Option	Description
--prompt	Prompt template with {dot.notation} payload references.
--events	Comma-separated event types to accept (e.g. issues,pull_request). Empty = all.
--description	Human-readable description.
--skills	Comma-separated skill names to load for the agent run.
--deliver	Delivery target: log (default), telegram, discord, slack, github_comment.
--deliver-chat-id	Target chat/channel ID for cross-platform delivery.
--secret	Custom HMAC secret. Auto-generated if omitted.

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

hermes doctor

hermes doctor [--fix]

Option	Description
--fix	Attempt automatic repairs where possible.

hermes config

hermes config <subcommand>

Subcommands:

Subcommand	Description
show	Show current config values.
edit	Open config.yaml in your editor.
set <key> <value>	Set a config value.
path	Print the config file path.
env-path	Print the .env file path.
check	Check for missing or stale config.
migrate	Add newly introduced options interactively.

hermes pairing

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

Subcommand	Description
list	Show pending and approved users.
approve <platform> <code>	Approve a pairing code.
revoke <platform> <user-id>	Revoke a user's access.
clear-pending	Clear pending pairing codes.

hermes skills

hermes skills <subcommand>

Subcommands:

Subcommand	Description
browse	Paginated browser for skill registries.
search	Search skill registries.
install	Install a skill.
inspect	Preview a skill without installing it.
list	List installed skills.
check	Check installed hub skills for upstream updates.
update	Reinstall hub skills with upstream changes when available.
audit	Re-scan installed hub skills.
uninstall	Remove a hub-installed skill.
publish	Publish a skill to a registry.
snapshot	Export/import skill configurations.
tap	Manage custom skill sources.
config	Interactive enable/disable configuration for skills by platform.

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:

Subcommand	Description
setup	Interactive Honcho setup wizard.
status	Show current Honcho config and connection status.
sessions	List known Honcho session mappings.
map	Map the current directory to a Honcho session name.
peer	Show or update peer names and dialectic reasoning level.
mode	Show or set memory mode: hybrid, honcho, or local.
tokens	Show or set token budgets for context and dialectic.
identity	Seed or show the AI peer identity representation.
migrate	Migration guide from openclaw-honcho to Hermes Honcho.

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.

Subcommand	Description
serve [-v|--verbose]	Run Hermes as an MCP server — expose conversations to other agents.
add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth|header]	Add an MCP server with automatic tool discovery.
remove <name> (alias: rm)	Remove an MCP server from config.
list (alias: ls)	List configured MCP servers.
test <name>	Test connection to an MCP server.
configure <name> (alias: config)	Toggle tool selection for a 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.

Subcommand	Description
(none)	Interactive toggle UI — enable/disable plugins with arrow keys and space.
install <identifier> [--force]	Install a plugin from a Git URL or owner/repo.
update <name>	Pull latest changes for an installed plugin.
remove <name> (aliases: rm, uninstall)	Remove an installed plugin.
enable <name>	Enable a disabled plugin.
disable <name>	Disable a plugin without removing it.
list (alias: ls)	List installed plugins with enabled/disabled status.

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]

Option	Description
--summary	Print the current enabled-tools summary and exit.

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

hermes sessions

hermes sessions <subcommand>

Subcommands:

Subcommand	Description
list	List recent sessions.
browse	Interactive session picker with search and resume.
export <output> [--session-id ID]	Export sessions to JSONL.
delete <session-id>	Delete one session.
prune	Delete old sessions.
stats	Show session-store statistics.
rename <session-id> <title>	Set or change a session title.

hermes insights

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

Option	Description
--days <n>	Analyze the last n days (default: 30).
--source <platform>	Filter by source such as cli, telegram, or discord.

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).

Option	Description
--dry-run	Preview what would be migrated without writing anything.
--preset <name>	Migration preset: full (default, includes secrets) or user-data (excludes API keys).
--overwrite	Overwrite existing Hermes files on conflicts (default: skip).
--migrate-secrets	Include API keys in migration (enabled by default with --preset full).
--source <path>	Custom OpenClaw directory (default: ~/.openclaw).
--workspace-target <path>	Target directory for workspace instructions (AGENTS.md).
--skill-conflict <mode>	Handle skill name collisions: skip (default), overwrite, or rename.
--yes	Skip the confirmation prompt.

What gets migrated

The migration covers your entire OpenClaw footprint. Items are either directly imported into Hermes equivalents or archived for manual review when there's no direct mapping.

Directly imported

Category	OpenClaw source	Hermes destination
Persona	SOUL.md	~/.hermes/SOUL.md
Workspace instructions	AGENTS.md	AGENTS.md in target workspace
Long-term memory	MEMORY.md	~/.hermes/MEMORY.md (merged with existing entries)
User profile	USER.md	~/.hermes/USER.md (merged with existing entries)
Daily memory files	workspace/memory/	Merged into ~/.hermes/MEMORY.md
Default model	Config model setting	config.yaml model section
Custom providers	Provider definitions (baseUrl, apiType, headers)	config.yaml custom_providers
MCP servers	MCP server definitions	config.yaml mcp_servers
User skills	Workspace skills	~/.hermes/skills/openclaw-imports/
Shared skills	~/.openclaw/skills/	~/.hermes/skills/openclaw-imports/
Personal skills	~/.agents/skills/ (cross-project)	~/.hermes/skills/openclaw-imports/
Project skills	workspace/.agents/skills/	~/.hermes/skills/openclaw-imports/
Command allowlist	Exec approval patterns	config.yaml command_allowlist
Messaging settings	Allowlists, working directory	config.yaml messaging section
Session policies	Daily/idle reset policies	config.yaml session_reset
Agent defaults	Compaction, context, thinking settings	config.yaml agent section
Browser settings	Browser automation config	config.yaml browser section
Tool settings	Exec timeout, sandbox, web search	config.yaml tools section
Approval rules	Approval mode and rules	config.yaml approvals section
TTS config	TTS provider and voice	config.yaml tts section
TTS assets	Workspace TTS files	~/.hermes/tts/
Gateway config	Gateway port and auth	config.yaml gateway section
Telegram settings	Bot token, allowlist	~/.hermes/.env
Discord settings	Bot token, allowlist	~/.hermes/.env
Slack settings	Bot/app tokens, allowlist	~/.hermes/.env
WhatsApp settings	Allowlist	~/.hermes/.env
Signal settings	Account, HTTP URL, allowlist	~/.hermes/.env
Channel config	Matrix, Mattermost, IRC, group settings	config.yaml + archive
Provider API keys	Config, ~/.openclaw/.env, and auth-profiles.json	~/.hermes/.env (requires --migrate-secrets)

Archived for manual review

These OpenClaw features don't have direct Hermes equivalents. They're saved to an archive directory for you to review and recreate manually.

Category	What's archived	How to recreate in Hermes
Cron / scheduled tasks	Job definitions	Recreate with hermes cron create
Plugins	Plugin configuration, installed extensions	Check the plugins guide
Hooks and webhooks	Internal hooks, webhooks, Gmail integration	Use hermes webhook or gateway hooks
Memory backend	QMD, vector search, citation settings	Configure Honcho via hermes honcho
Skills registry	Per-skill enabled/config/env settings	Use hermes skills config
UI and identity	Theme, assistant identity, display prefs	Use /skin command or config.yaml
Logging	Diagnostics configuration	Set in config.yaml logging section

Security

API keys are not migrated by default. The --preset full preset enables secret migration. Keys are collected from three sources (config values take priority, then .env, then auth-profiles.json) for these targets: OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, ELEVENLABS_API_KEY, TELEGRAM_BOT_TOKEN, and VOICE_TOOLS_OPENAI_KEY. All other secrets are skipped.

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

# Migrate and place AGENTS.md in a specific project
hermes claw migrate --workspace-target /home/user/my-project

Maintenance commands

Command	Description
hermes version	Print version information.
hermes update	Pull latest changes and reinstall dependencies.
hermes uninstall [--full] [--yes]	Remove Hermes, optionally deleting all config/data.

See also

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