cli-commands.md
1 --- 2 sidebar_position: 1 3 title: "CLI Commands Reference" 4 description: "Authoritative reference for Hermes terminal commands and command families" 5 --- 6 7 # CLI Commands Reference 8 9 This page covers the **terminal commands** you run from your shell. 10 11 For in-chat slash commands, see [Slash Commands Reference](./slash-commands.md). 12 13 ## Global entrypoint 14 15 ```bash 16 hermes [global-options] <command> [subcommand/options] 17 ``` 18 19 ### Global options 20 21 | Option | Description | 22 |--------|-------------| 23 | `--version`, `-V` | Show version and exit. | 24 | `--profile <name>`, `-p <name>` | Select which Hermes profile to use for this invocation. Overrides the sticky default set by `hermes profile use`. | 25 | `--resume <session>`, `-r <session>` | Resume a previous session by ID or title. | 26 | `--continue [name]`, `-c [name]` | Resume the most recent session, or the most recent session matching a title. | 27 | `--worktree`, `-w` | Start in an isolated git worktree for parallel-agent workflows. | 28 | `--yolo` | Bypass dangerous-command approval prompts. | 29 | `--pass-session-id` | Include the session ID in the agent's system prompt. | 30 | `--ignore-user-config` | Ignore `~/.hermes/config.yaml` and fall back to built-in defaults. Credentials in `.env` are still loaded. | 31 | `--ignore-rules` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, memory, and preloaded skills. | 32 | `--tui` | Launch the [TUI](../user-guide/tui.md) instead of the classic CLI. Equivalent to `HERMES_TUI=1`. | 33 | `--dev` | With `--tui`: run the TypeScript sources directly via `tsx` instead of the prebuilt bundle (for TUI contributors). | 34 35 ## Top-level commands 36 37 | Command | Purpose | 38 |---------|---------| 39 | `hermes chat` | Interactive or one-shot chat with the agent. | 40 | `hermes model` | Interactively choose the default provider and model. | 41 | `hermes fallback` | Manage fallback providers tried when the primary model errors. | 42 | `hermes gateway` | Run or manage the messaging gateway service. | 43 | `hermes setup` | Interactive setup wizard for all or part of the configuration. | 44 | `hermes whatsapp` | Configure and pair the WhatsApp bridge. | 45 | `hermes slack` | Slack helpers (currently: generate the app manifest with every command as a native slash). | 46 | `hermes auth` | Manage credentials — add, list, remove, reset, set strategy. Handles OAuth flows for Codex/Nous/Anthropic. | 47 | `hermes login` / `logout` | **Deprecated** — use `hermes auth` instead. | 48 | `hermes status` | Show agent, auth, and platform status. | 49 | `hermes cron` | Inspect and tick the cron scheduler. | 50 | `hermes kanban` | Multi-profile collaboration board (tasks, links, dispatcher). | 51 | `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. | 52 | `hermes hooks` | Inspect, approve, or remove shell-script hooks declared in `config.yaml`. | 53 | `hermes doctor` | Diagnose config and dependency issues. | 54 | `hermes dump` | Copy-pasteable setup summary for support/debugging. | 55 | `hermes debug` | Debug tools — upload logs and system info for support. | 56 | `hermes backup` | Back up Hermes home directory to a zip file. | 57 | `hermes import` | Restore a Hermes backup from a zip file. | 58 | `hermes logs` | View, tail, and filter agent/gateway/error log files. | 59 | `hermes config` | Show, edit, migrate, and query configuration files. | 60 | `hermes pairing` | Approve or revoke messaging pairing codes. | 61 | `hermes skills` | Browse, install, publish, audit, and configure skills. | 62 | `hermes curator` | Background skill maintenance — status, run, pause, pin. See [Curator](../user-guide/features/curator.md). | 63 | `hermes memory` | Configure external memory provider. Plugin-specific subcommands (e.g. `hermes honcho`) register automatically when their provider is active. | 64 | `hermes acp` | Run Hermes as an ACP server for editor integration. | 65 | `hermes mcp` | Manage MCP server configurations and run Hermes as an MCP server. | 66 | `hermes plugins` | Manage Hermes Agent plugins (install, enable, disable, remove). | 67 | `hermes tools` | Configure enabled tools per platform. | 68 | `hermes sessions` | Browse, export, prune, rename, and delete sessions. | 69 | `hermes insights` | Show token/cost/activity analytics. | 70 | `hermes fallback` | Interactive manager for the fallback provider chain. | 71 | `hermes claw` | OpenClaw migration helpers. | 72 | `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. | 73 | `hermes profile` | Manage profiles — multiple isolated Hermes instances. | 74 | `hermes completion` | Print shell completion scripts (bash/zsh/fish). | 75 | `hermes version` | Show version information. | 76 | `hermes update` | Pull latest code and reinstall dependencies. `--check` prints commit diff without pulling; `--backup` takes a pre-pull `HERMES_HOME` snapshot. | 77 | `hermes uninstall` | Remove Hermes from the system. | 78 79 ## `hermes chat` 80 81 ```bash 82 hermes chat [options] 83 ``` 84 85 Common options: 86 87 | Option | Description | 88 |--------|-------------| 89 | `-q`, `--query "..."` | One-shot, non-interactive prompt. | 90 | `-m`, `--model <model>` | Override the model for this run. | 91 | `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. | 92 | `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot-acp`, `copilot`, `anthropic`, `gemini`, `google-gemini-cli`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `alibaba-coding-plan` (alias `alibaba_coding`), `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway`, `azure-foundry`, `tencent-tokenhub` (alias `tencent`, `tokenhub`). | 93 | `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). | 94 | `-v`, `--verbose` | Verbose output. | 95 | `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. | 96 | `--image <path>` | Attach a local image to a single query. | 97 | `--resume <session>` / `--continue [name]` | Resume a session directly from `chat`. | 98 | `--worktree` | Create an isolated git worktree for this run. | 99 | `--checkpoints` | Enable filesystem checkpoints before destructive file changes. | 100 | `--yolo` | Skip approval prompts. | 101 | `--pass-session-id` | Pass the session ID into the system prompt. | 102 | `--ignore-user-config` | Ignore `~/.hermes/config.yaml` and use built-in defaults. Credentials in `.env` are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations. | 103 | `--ignore-rules` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, persistent memory, and preloaded skills. Combine with `--ignore-user-config` for a fully isolated run. | 104 | `--source <tag>` | Session source tag for filtering (default: `cli`). Use `tool` for third-party integrations that should not appear in user session lists. | 105 | `--max-turns <N>` | Maximum tool-calling iterations per conversation turn (default: 90, or `agent.max_turns` in config). | 106 107 Examples: 108 109 ```bash 110 hermes 111 hermes chat -q "Summarize the latest PRs" 112 hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6 113 hermes chat --toolsets web,terminal,skills 114 hermes chat --quiet -q "Return only JSON" 115 hermes chat --worktree -q "Review this repo and open a PR" 116 hermes chat --ignore-user-config --ignore-rules -q "Repro without my personal setup" 117 ``` 118 119 ### `hermes -z <prompt>` — scripted one-shot 120 121 For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), `hermes -z` is the purest one-shot entry point: **single prompt in, final response text out, nothing else on stdout or stderr.** No banner, no spinner, no tool previews, no `Session:` line — just the agent's final reply as plain text. 122 123 ```bash 124 hermes -z "What's the capital of France?" 125 # → Paris. 126 127 # Parent scripts can cleanly capture the response: 128 answer=$(hermes -z "summarize this" < /path/to/file.txt) 129 ``` 130 131 Per-run overrides (no mutation to `~/.hermes/config.yaml`): 132 133 | Flag | Equivalent env var | Purpose | 134 |---|---|---| 135 | `-m` / `--model <model>` | `HERMES_INFERENCE_MODEL` | Override the model for this run | 136 | `--provider <provider>` | `HERMES_INFERENCE_PROVIDER` | Override the provider for this run | 137 138 ```bash 139 hermes -z "…" --provider openrouter --model openai/gpt-5.5 140 # or: 141 HERMES_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 hermes -z "…" 142 ``` 143 144 Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use `hermes chat -q` instead; `-z` is explicitly for "I only want the final answer". 145 146 ## `hermes model` 147 148 Interactive provider + model selector. **This is the command for adding new providers, setting up API keys, and running OAuth flows.** Run it from your terminal — not from inside an active Hermes chat session. 149 150 ```bash 151 hermes model 152 ``` 153 154 Use this when you want to: 155 - **add a new provider** (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.) 156 - log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal) 157 - enter or update API keys 158 - pick from provider-specific model lists 159 - configure a custom/self-hosted endpoint 160 - save the new default into config 161 162 :::warning hermes model vs /model — know the difference 163 **`hermes model`** (run from your terminal, outside any Hermes session) is the **full provider setup wizard**. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints. 164 165 **`/model`** (typed inside an active Hermes chat session) can only **switch between providers and models you've already set up**. It cannot add new providers, run OAuth, or prompt for API keys. 166 167 **If you need to add a new provider:** Exit your Hermes session first (`Ctrl+C` or `/quit`), then run `hermes model` from your terminal prompt. 168 ::: 169 170 ### `/model` slash command (mid-session) 171 172 Switch between already-configured models without leaving a session: 173 174 ``` 175 /model # Show current model and available options 176 /model claude-sonnet-4 # Switch model (auto-detects provider) 177 /model zai:glm-5 # Switch provider and model 178 /model custom:qwen-2.5 # Use model on your custom endpoint 179 /model custom # Auto-detect model from custom endpoint 180 /model custom:local:qwen-2.5 # Use a named custom provider 181 /model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud 182 ``` 183 184 By default, `/model` changes apply **to the current session only**. Add `--global` to persist the change to `config.yaml`: 185 186 ``` 187 /model claude-sonnet-4 --global # Switch and save as new default 188 ``` 189 190 :::info What if I only see OpenRouter models? 191 If you've only configured OpenRouter, `/model` will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run `hermes model` from the terminal. 192 ::: 193 194 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. 195 196 ## `hermes gateway` 197 198 ```bash 199 hermes gateway <subcommand> 200 ``` 201 202 Subcommands: 203 204 | Subcommand | Description | 205 |------------|-------------| 206 | `run` | Run the gateway in the foreground. Recommended for WSL, Docker, and Termux. | 207 | `start` | Start the installed systemd/launchd background service. | 208 | `stop` | Stop the service (or foreground process). | 209 | `restart` | Restart the service. | 210 | `status` | Show service status. | 211 | `install` | Install as a systemd (Linux) or launchd (macOS) background service. | 212 | `uninstall` | Remove the installed service. | 213 | `setup` | Interactive messaging-platform setup. | 214 215 Options: 216 217 | Option | Description | 218 |--------|-------------| 219 | `--all` | On `start` / `restart` / `stop`: act on **every profile's** gateway, not just the active `HERMES_HOME`. Useful if you run multiple profiles side-by-side and want to restart them all after `hermes update`. | 220 221 :::tip WSL users 222 Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See [WSL FAQ](/docs/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails) for details. 223 ::: 224 225 ## `hermes setup` 226 227 ```bash 228 hermes setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure] 229 ``` 230 231 **First run:** launches the first-time wizard. 232 233 **Returning user (already configured):** drops straight into the full reconfigure wizard — every prompt shows your current value as its default, press Enter to keep or type a new value. No menu. 234 235 Jump into one section instead of the full wizard: 236 237 | Section | Description | 238 |---------|-------------| 239 | `model` | Provider and model setup. | 240 | `terminal` | Terminal backend and sandbox setup. | 241 | `gateway` | Messaging platform setup. | 242 | `tools` | Enable/disable tools per platform. | 243 | `agent` | Agent behavior settings. | 244 245 Options: 246 247 | Option | Description | 248 |--------|-------------| 249 | `--quick` | On returning-user runs: only prompt for items that are missing or unset. Skip items you already have configured. | 250 | `--non-interactive` | Use defaults / environment values without prompts. | 251 | `--reset` | Reset configuration to defaults before setup. | 252 | `--reconfigure` | Backwards-compat alias — bare `hermes setup` on an existing install now does this by default. | 253 254 ## `hermes whatsapp` 255 256 ```bash 257 hermes whatsapp 258 ``` 259 260 Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing. 261 262 ## `hermes slack` 263 264 ```bash 265 hermes slack manifest # print manifest to stdout 266 hermes slack manifest --write # write to ~/.hermes/slack-manifest.json 267 hermes slack manifest --slashes-only # just the features.slash_commands array 268 ``` 269 270 Generates a Slack app manifest that registers every gateway command in 271 `COMMAND_REGISTRY` (`/btw`, `/stop`, `/model`, …) as a first-class 272 Slack slash command — matching Discord and Telegram parity. Paste the 273 output into your Slack app config at 274 [https://api.slack.com/apps](https://api.slack.com/apps) → your app → 275 **Features → App Manifest → Edit**, then **Save**. Slack prompts for 276 reinstall if scopes or slash commands changed. 277 278 | Flag | Default | Purpose | 279 |------|---------|---------| 280 | `--write [PATH]` | stdout | Write to a file instead of stdout. Bare `--write` writes `$HERMES_HOME/slack-manifest.json`. | 281 | `--name NAME` | `Hermes` | Bot display name in Slack. | 282 | `--description DESC` | default blurb | Bot description shown in the Slack app directory. | 283 | `--slashes-only` | off | Emit only `features.slash_commands` for merging into a manually-maintained manifest. | 284 285 Run `hermes slack manifest --write` again after `hermes update` to pick 286 up any new commands. 287 288 289 ## `hermes login` / `hermes logout` *(Deprecated)* 290 291 :::caution 292 `hermes login` has been removed. Use `hermes auth` to manage OAuth credentials, `hermes model` to select a provider, or `hermes setup` for full interactive setup. 293 ::: 294 295 ## `hermes auth` 296 297 Manage credential pools for same-provider key rotation. See [Credential Pools](/docs/user-guide/features/credential-pools) for full documentation. 298 299 ```bash 300 hermes auth # Interactive wizard 301 hermes auth list # Show all pools 302 hermes auth list openrouter # Show specific provider 303 hermes auth add openrouter --api-key sk-or-v1-xxx # Add API key 304 hermes auth add anthropic --type oauth # Add OAuth credential 305 hermes auth remove openrouter 2 # Remove by index 306 hermes auth reset openrouter # Clear cooldowns 307 ``` 308 309 Subcommands: `add`, `list`, `remove`, `reset`. When called with no subcommand, launches the interactive management wizard. 310 311 ## `hermes status` 312 313 ```bash 314 hermes status [--all] [--deep] 315 ``` 316 317 | Option | Description | 318 |--------|-------------| 319 | `--all` | Show all details in a shareable redacted format. | 320 | `--deep` | Run deeper checks that may take longer. | 321 322 ## `hermes cron` 323 324 ```bash 325 hermes cron <list|create|edit|pause|resume|run|remove|status|tick> 326 ``` 327 328 | Subcommand | Description | 329 |------------|-------------| 330 | `list` | Show scheduled jobs. | 331 | `create` / `add` | Create a scheduled job from a prompt, optionally attaching one or more skills via repeated `--skill`. | 332 | `edit` | Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports `--clear-skills`, `--add-skill`, and `--remove-skill`. | 333 | `pause` | Pause a job without deleting it. | 334 | `resume` | Resume a paused job and compute its next future run. | 335 | `run` | Trigger a job on the next scheduler tick. | 336 | `remove` | Delete a scheduled job. | 337 | `status` | Check whether the cron scheduler is running. | 338 | `tick` | Run due jobs once and exit. | 339 340 ## `hermes kanban` 341 342 ```bash 343 hermes kanban [--board <slug>] <action> [options] 344 ``` 345 346 Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called `default`, whose DB is `~/.hermes/kanban.db` for back-compat; additional boards live at `~/.hermes/kanban/boards/<slug>/kanban.db`. The gateway-embedded dispatcher sweeps every board per tick. 347 348 **Global flags (apply to every action below):** 349 350 | Flag | Purpose | 351 |------|---------| 352 | `--board <slug>` | Operate on a specific board. Defaults to the current board (set via `hermes kanban boards switch`, the `HERMES_KANBAN_BOARD` env var, or `default`). | 353 354 **This is the human / scripting surface.** Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_*` [toolset](/docs/user-guide/features/kanban#how-workers-interact-with-the-board) (`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`) instead of shelling to `hermes kanban`. Workers have `HERMES_KANBAN_BOARD` pinned in their env so they physically cannot see other boards. 355 356 | Action | Purpose | 357 |--------|---------| 358 | `init` | Create `kanban.db` if missing. Idempotent. | 359 | `boards list` / `boards ls` | List all boards with task counts. `--json`, `--all` (include archived). | 360 | `boards create <slug>` | Create a new board. Flags: `--name`, `--description`, `--icon`, `--color`, `--switch` (make active). Slug is kebab-case, auto-downcased. | 361 | `boards switch <slug>` / `boards use` | Persist `<slug>` as the active board (writes `~/.hermes/kanban/current`). | 362 | `boards show` / `boards current` | Print the currently-active board's name, DB path, and task counts. | 363 | `boards rename <slug> "<name>"` | Change a board's display name. Slug is immutable. | 364 | `boards rm <slug>` | Archive (default) or hard-delete a board. `--delete` skips the archive step. Archived boards move to `boards/_archived/<slug>-<ts>/`. Refused for `default`. | 365 | `create "<title>"` | Create a new task on the active board. Flags: `--body`, `--assignee`, `--parent` (repeatable), `--workspace scratch\|worktree\|dir:<path>`, `--tenant`, `--priority`, `--triage`, `--idempotency-key`, `--max-runtime`, `--skill` (repeatable). | 366 | `list` / `ls` | List tasks on the active board. Filter with `--mine`, `--assignee`, `--status`, `--tenant`, `--archived`, `--json`. | 367 | `show <id>` | Show a task with comments and events. `--json` for machine output. | 368 | `assign <id> <profile>` | Assign or reassign. Use `none` to unassign. Refused while task is running. | 369 | `link <parent> <child>` | Add a dependency. Cycle-detected. Both tasks must be on the same board. | 370 | `unlink <parent> <child>` | Remove a dependency. | 371 | `claim <id>` | Atomically claim a ready task. Prints resolved workspace path. | 372 | `comment <id> "<text>"` | Append a comment. The next worker that claims the task reads it as part of its `kanban_show()` response. | 373 | `complete <id>` | Mark task done. Flags: `--result`, `--summary`, `--metadata`. | 374 | `block <id> "<reason>"` | Mark task blocked. Also appends the reason as a comment. | 375 | `unblock <id>` | Return a blocked task to ready. | 376 | `archive <id>` | Hide from default list. `gc` will remove scratch workspaces. | 377 | `tail <id>` | Follow a task's event stream. | 378 | `dispatch` | One dispatcher pass on the active board. Flags: `--dry-run`, `--max N`, `--json`. | 379 | `context <id>` | Print the full context a worker would see (title + body + parent results + comments). | 380 | `gc` | Remove scratch workspaces for archived tasks. | 381 382 Examples: 383 384 ```bash 385 # Create a second board and put a task on it without switching away. 386 hermes kanban boards create atm10-server --name "ATM10 Server" --icon 🎮 387 hermes kanban --board atm10-server create "Restart server" --assignee ops 388 389 # Switch the active board for subsequent calls. 390 hermes kanban boards switch atm10-server 391 hermes kanban list # shows atm10-server tasks 392 393 # Archive a board (recoverable) or hard-delete it. 394 hermes kanban boards rm atm10-server 395 hermes kanban boards rm atm10-server --delete 396 ``` 397 398 Board resolution order (highest precedence first): `--board <slug>` flag → `HERMES_KANBAN_BOARD` env var → `~/.hermes/kanban/current` file → `default`. 399 400 All actions are also available as a slash command in the gateway (`/kanban …`), with the same argument surface — including `boards` subcommands and the `--board` flag. 401 402 For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see `docs/hermes-kanban-v1-spec.pdf` in the repository or the [Kanban user guide](/docs/user-guide/features/kanban). 403 404 ## `hermes webhook` 405 406 ```bash 407 hermes webhook <subscribe|list|remove|test> 408 ``` 409 410 Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions. 411 412 | Subcommand | Description | 413 |------------|-------------| 414 | `subscribe` / `add` | Create a webhook route. Returns the URL and HMAC secret to configure on your service. | 415 | `list` / `ls` | Show all agent-created subscriptions. | 416 | `remove` / `rm` | Delete a dynamic subscription. Static routes from config.yaml are not affected. | 417 | `test` | Send a test POST to verify a subscription is working. | 418 419 ### `hermes webhook subscribe` 420 421 ```bash 422 hermes webhook subscribe <name> [options] 423 ``` 424 425 | Option | Description | 426 |--------|-------------| 427 | `--prompt` | Prompt template with `{dot.notation}` payload references. | 428 | `--events` | Comma-separated event types to accept (e.g. `issues,pull_request`). Empty = all. | 429 | `--description` | Human-readable description. | 430 | `--skills` | Comma-separated skill names to load for the agent run. | 431 | `--deliver` | Delivery target: `log` (default), `telegram`, `discord`, `slack`, `github_comment`. | 432 | `--deliver-chat-id` | Target chat/channel ID for cross-platform delivery. | 433 | `--secret` | Custom HMAC secret. Auto-generated if omitted. | 434 435 Subscriptions persist to `~/.hermes/webhook_subscriptions.json` and are hot-reloaded by the webhook adapter without a gateway restart. 436 437 ## `hermes doctor` 438 439 ```bash 440 hermes doctor [--fix] 441 ``` 442 443 | Option | Description | 444 |--------|-------------| 445 | `--fix` | Attempt automatic repairs where possible. | 446 447 ## `hermes dump` 448 449 ```bash 450 hermes dump [--show-keys] 451 ``` 452 453 Outputs a compact, plain-text summary of your entire Hermes setup. Designed to be copy-pasted into Discord, GitHub issues, or Telegram when asking for support — no ANSI colors, no special formatting, just data. 454 455 | Option | Description | 456 |--------|-------------| 457 | `--show-keys` | Show redacted API key prefixes (first and last 4 characters) instead of just `set`/`not set`. | 458 459 ### What it includes 460 461 | Section | Details | 462 |---------|---------| 463 | **Header** | Hermes version, release date, git commit hash | 464 | **Environment** | OS, Python version, OpenAI SDK version | 465 | **Identity** | Active profile name, HERMES_HOME path | 466 | **Model** | Configured default model and provider | 467 | **Terminal** | Backend type (local, docker, ssh, etc.) | 468 | **API keys** | Presence check for all 22 provider/tool API keys | 469 | **Features** | Enabled toolsets, MCP server count, memory provider | 470 | **Services** | Gateway status, configured messaging platforms | 471 | **Workload** | Cron job counts, installed skill count | 472 | **Config overrides** | Any config values that differ from defaults | 473 474 ### Example output 475 476 ``` 477 --- hermes dump --- 478 version: 0.8.0 (2026.4.8) [af4abd2f] 479 os: Linux 6.14.0-37-generic x86_64 480 python: 3.11.14 481 openai_sdk: 2.24.0 482 profile: default 483 hermes_home: ~/.hermes 484 model: anthropic/claude-opus-4.6 485 provider: openrouter 486 terminal: local 487 488 api_keys: 489 openrouter set 490 openai not set 491 anthropic set 492 nous not set 493 firecrawl set 494 ... 495 496 features: 497 toolsets: all 498 mcp_servers: 0 499 memory_provider: built-in 500 gateway: running (systemd) 501 platforms: telegram, discord 502 cron_jobs: 3 active / 5 total 503 skills: 42 504 505 config_overrides: 506 agent.max_turns: 250 507 compression.threshold: 0.85 508 display.streaming: True 509 --- end dump --- 510 ``` 511 512 ### When to use 513 514 - Reporting a bug on GitHub — paste the dump into your issue 515 - Asking for help in Discord — share it in a code block 516 - Comparing your setup to someone else's 517 - Quick sanity check when something isn't working 518 519 :::tip 520 `hermes dump` is specifically designed for sharing. For interactive diagnostics, use `hermes doctor`. For a visual overview, use `hermes status`. 521 ::: 522 523 ## `hermes debug` 524 525 ```bash 526 hermes debug share [options] 527 ``` 528 529 Upload a debug report (system info + recent logs) to a paste service and get a shareable URL. Useful for quick support requests — includes everything a helper needs to diagnose your issue. 530 531 | Option | Description | 532 |--------|-------------| 533 | `--lines <N>` | Number of log lines to include per log file (default: 200). | 534 | `--expire <days>` | Paste expiry in days (default: 7). | 535 | `--local` | Print the report locally instead of uploading. | 536 537 The report includes system info (OS, Python version, Hermes version), recent agent and gateway logs (512 KB limit per file), and redacted API key status. Keys are always redacted — no secrets are uploaded. 538 539 Paste services tried in order: paste.rs, dpaste.com. 540 541 ### Examples 542 543 ```bash 544 hermes debug share # Upload debug report, print URL 545 hermes debug share --lines 500 # Include more log lines 546 hermes debug share --expire 30 # Keep paste for 30 days 547 hermes debug share --local # Print report to terminal (no upload) 548 ``` 549 550 ## `hermes backup` 551 552 ```bash 553 hermes backup [options] 554 ``` 555 556 Create a zip archive of your Hermes configuration, skills, sessions, and data. The backup excludes the hermes-agent codebase itself. 557 558 | Option | Description | 559 |--------|-------------| 560 | `-o`, `--output <path>` | Output path for the zip file (default: `~/hermes-backup-<timestamp>.zip`). | 561 | `-q`, `--quick` | Quick snapshot: only critical state files (config.yaml, state.db, .env, auth, cron jobs). Much faster than a full backup. | 562 | `-l`, `--label <name>` | Label for the snapshot (only used with `--quick`). | 563 564 The backup uses SQLite's `backup()` API for safe copying, so it works correctly even when Hermes is running (WAL-mode safe). 565 566 **What's excluded from the zip:** 567 568 - `*.db-wal`, `*.db-shm`, `*.db-journal` — SQLite's WAL / shared-memory / journal sidecars. The `*.db` file already got a consistent snapshot via `sqlite3.backup()`; shipping the live sidecars alongside it would let a restore see a half-committed state. 569 - `checkpoints/` — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn't port cleanly to another install anyway. 570 - The `hermes-agent` code itself (this is a user-data backup, not a repo snapshot). 571 572 ### Examples 573 574 ```bash 575 hermes backup # Full backup to ~/hermes-backup-*.zip 576 hermes backup -o /tmp/hermes.zip # Full backup to specific path 577 hermes backup --quick # Quick state-only snapshot 578 hermes backup --quick --label "pre-upgrade" # Quick snapshot with label 579 ``` 580 581 ## `hermes import` 582 583 ```bash 584 hermes import <zipfile> [options] 585 ``` 586 587 Restore a previously created Hermes backup into your Hermes home directory. 588 589 | Option | Description | 590 |--------|-------------| 591 | `-f`, `--force` | Overwrite existing files without confirmation. | 592 593 ## `hermes logs` 594 595 ```bash 596 hermes logs [log_name] [options] 597 ``` 598 599 View, tail, and filter Hermes log files. All logs are stored in `~/.hermes/logs/` (or `<profile>/logs/` for non-default profiles). 600 601 ### Log files 602 603 | Name | File | What it captures | 604 |------|------|-----------------| 605 | `agent` (default) | `agent.log` | All agent activity — API calls, tool dispatch, session lifecycle (INFO and above) | 606 | `errors` | `errors.log` | Warnings and errors only — a filtered subset of agent.log | 607 | `gateway` | `gateway.log` | Messaging gateway activity — platform connections, message dispatch, webhook events | 608 609 ### Options 610 611 | Option | Description | 612 |--------|-------------| 613 | `log_name` | Which log to view: `agent` (default), `errors`, `gateway`, or `list` to show available files with sizes. | 614 | `-n`, `--lines <N>` | Number of lines to show (default: 50). | 615 | `-f`, `--follow` | Follow the log in real time, like `tail -f`. Press Ctrl+C to stop. | 616 | `--level <LEVEL>` | Minimum log level to show: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | 617 | `--session <ID>` | Filter lines containing a session ID substring. | 618 | `--since <TIME>` | Show lines from a relative time ago: `30m`, `1h`, `2d`, etc. Supports `s` (seconds), `m` (minutes), `h` (hours), `d` (days). | 619 | `--component <NAME>` | Filter by component: `gateway`, `agent`, `tools`, `cli`, `cron`. | 620 621 ### Examples 622 623 ```bash 624 # View the last 50 lines of agent.log (default) 625 hermes logs 626 627 # Follow agent.log in real time 628 hermes logs -f 629 630 # View the last 100 lines of gateway.log 631 hermes logs gateway -n 100 632 633 # Show only warnings and errors from the last hour 634 hermes logs --level WARNING --since 1h 635 636 # Filter by a specific session 637 hermes logs --session abc123 638 639 # Follow errors.log, starting from 30 minutes ago 640 hermes logs errors --since 30m -f 641 642 # List all log files with their sizes 643 hermes logs list 644 ``` 645 646 ### Filtering 647 648 Filters can be combined. When multiple filters are active, a log line must pass **all** of them to be shown: 649 650 ```bash 651 # WARNING+ lines from the last 2 hours containing session "tg-12345" 652 hermes logs --level WARNING --since 2h --session tg-12345 653 ``` 654 655 Lines without a parseable timestamp are included when `--since` is active (they may be continuation lines from a multi-line log entry). Lines without a detectable level are included when `--level` is active. 656 657 ### Log rotation 658 659 Hermes uses Python's `RotatingFileHandler`. Old logs are rotated automatically — look for `agent.log.1`, `agent.log.2`, etc. The `hermes logs list` subcommand shows all log files including rotated ones. 660 661 ## `hermes config` 662 663 ```bash 664 hermes config <subcommand> 665 ``` 666 667 Subcommands: 668 669 | Subcommand | Description | 670 |------------|-------------| 671 | `show` | Show current config values. | 672 | `edit` | Open `config.yaml` in your editor. | 673 | `set <key> <value>` | Set a config value. | 674 | `path` | Print the config file path. | 675 | `env-path` | Print the `.env` file path. | 676 | `check` | Check for missing or stale config. | 677 | `migrate` | Add newly introduced options interactively. | 678 679 ## `hermes pairing` 680 681 ```bash 682 hermes pairing <list|approve|revoke|clear-pending> 683 ``` 684 685 | Subcommand | Description | 686 |------------|-------------| 687 | `list` | Show pending and approved users. | 688 | `approve <platform> <code>` | Approve a pairing code. | 689 | `revoke <platform> <user-id>` | Revoke a user's access. | 690 | `clear-pending` | Clear pending pairing codes. | 691 692 ## `hermes skills` 693 694 ```bash 695 hermes skills <subcommand> 696 ``` 697 698 Subcommands: 699 700 | Subcommand | Description | 701 |------------|-------------| 702 | `browse` | Paginated browser for skill registries. | 703 | `search` | Search skill registries. | 704 | `install` | Install a skill. | 705 | `inspect` | Preview a skill without installing it. | 706 | `list` | List installed skills. | 707 | `check` | Check installed hub skills for upstream updates. | 708 | `update` | Reinstall hub skills with upstream changes when available. | 709 | `audit` | Re-scan installed hub skills. | 710 | `uninstall` | Remove a hub-installed skill. | 711 | `publish` | Publish a skill to a registry. | 712 | `snapshot` | Export/import skill configurations. | 713 | `tap` | Manage custom skill sources. | 714 | `config` | Interactive enable/disable configuration for skills by platform. | 715 716 Common examples: 717 718 ```bash 719 hermes skills browse 720 hermes skills browse --source official 721 hermes skills search react --source skills-sh 722 hermes skills search https://mintlify.com/docs --source well-known 723 hermes skills inspect official/security/1password 724 hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react 725 hermes skills install official/migration/openclaw-migration 726 hermes skills install skills-sh/anthropics/skills/pdf --force 727 hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md) 728 hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none 729 hermes skills check 730 hermes skills update 731 hermes skills config 732 ``` 733 734 Notes: 735 - `--force` can override non-dangerous policy blocks for third-party/community skills. 736 - `--force` does not override a `dangerous` scan verdict. 737 - `--source skills-sh` searches the public `skills.sh` directory. 738 - `--source well-known` lets you point Hermes at a site exposing `/.well-known/skills/index.json`. 739 - Passing an `http(s)://…/*.md` URL installs a single-file SKILL.md directly. When frontmatter has no `name:` and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (`/skills install` inside the TUI, gateway platforms) require `--name <x>` instead. 740 741 ## `hermes curator` 742 743 ```bash 744 hermes curator <subcommand> 745 ``` 746 747 The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens. 748 749 | Subcommand | Description | 750 |------------|-------------| 751 | `status` | Show curator status and skill stats | 752 | `run` | Trigger a curator review now | 753 | `run --sync` | Block until the LLM pass finishes | 754 | `run --dry-run` | Preview only — produce the review report with no mutations | 755 | `backup` | Take a manual tar.gz snapshot of `~/.hermes/skills/` (curator also snapshots automatically before every real run) | 756 | `rollback` | Restore `~/.hermes/skills/` from a snapshot (defaults to newest) | 757 | `rollback --list` | List available snapshots | 758 | `rollback --id <ts>` | Restore a specific snapshot by id | 759 | `rollback -y` | Skip the confirmation prompt | 760 | `pause` | Pause the curator until resumed | 761 | `resume` | Resume a paused curator | 762 | `pin <skill>` | Pin a skill so the curator never auto-transitions it | 763 | `unpin <skill>` | Unpin a skill | 764 | `restore <skill>` | Restore an archived skill | 765 766 On a fresh install the first scheduled pass is deferred by one full `interval_hours` (7 days by default) — the gateway will not curate immediately on the first tick after `hermes update`. Use `hermes curator run --dry-run` to preview before that happens. 767 768 See [Curator](../user-guide/features/curator.md) for behavior and config. 769 770 ## `hermes fallback` 771 772 ```bash 773 hermes fallback <subcommand> 774 ``` 775 776 Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors. 777 778 | Subcommand | Description | 779 |------------|-------------| 780 | `list` (alias: `ls`) | Show the current fallback chain (default when no subcommand) | 781 | `add` | Pick a provider + model (same picker as `hermes model`) and append to the chain | 782 | `remove` (alias: `rm`) | Pick an entry to delete from the chain | 783 | `clear` | Remove all fallback entries | 784 785 See [Fallback Providers](../user-guide/features/fallback-providers.md). 786 787 ## `hermes hooks` 788 789 ```bash 790 hermes hooks <subcommand> 791 ``` 792 793 Inspect shell-script hooks declared in `~/.hermes/config.yaml`, test them against synthetic payloads, and manage the first-use consent allowlist at `~/.hermes/shell-hooks-allowlist.json`. 794 795 | Subcommand | Description | 796 |------------|-------------| 797 | `list` (alias: `ls`) | List configured hooks with matcher, timeout, and consent status | 798 | `test <event>` | Fire every hook matching `<event>` against a synthetic payload | 799 | `revoke` (aliases: `remove`, `rm`) | Remove a command's allowlist entries (takes effect on next restart) | 800 | `doctor` | Check each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing | 801 802 See [Hooks](../user-guide/features/hooks.md) for event signatures and payload shapes. 803 804 ## `hermes memory` 805 806 ```bash 807 hermes memory <subcommand> 808 ``` 809 810 Set up and manage external memory provider plugins. Available providers: honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. Only one external provider can be active at a time. Built-in memory (MEMORY.md/USER.md) is always active. 811 812 Subcommands: 813 814 | Subcommand | Description | 815 |------------|-------------| 816 | `setup` | Interactive provider selection and configuration. | 817 | `status` | Show current memory provider config. | 818 | `off` | Disable external provider (built-in only). | 819 820 :::info Provider-specific subcommands 821 When an external memory provider is active, it may register its own top-level `hermes <provider>` command for provider-specific management (e.g. `hermes honcho` when Honcho is active). Inactive providers do not expose their subcommands. Run `hermes --help` to see what's currently wired in. 822 ::: 823 824 ## `hermes acp` 825 826 ```bash 827 hermes acp 828 ``` 829 830 Starts Hermes as an ACP (Agent Client Protocol) stdio server for editor integration. 831 832 Related entrypoints: 833 834 ```bash 835 hermes-acp 836 python -m acp_adapter 837 ``` 838 839 Install support first: 840 841 ```bash 842 pip install -e '.[acp]' 843 ``` 844 845 See [ACP Editor Integration](../user-guide/features/acp.md) and [ACP Internals](../developer-guide/acp-internals.md). 846 847 ## `hermes mcp` 848 849 ```bash 850 hermes mcp <subcommand> 851 ``` 852 853 Manage MCP (Model Context Protocol) server configurations and run Hermes as an MCP server. 854 855 | Subcommand | Description | 856 |------------|-------------| 857 | `serve [-v\|--verbose]` | Run Hermes as an MCP server — expose conversations to other agents. | 858 | `add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth\|header]` | Add an MCP server with automatic tool discovery. | 859 | `remove <name>` (alias: `rm`) | Remove an MCP server from config. | 860 | `list` (alias: `ls`) | List configured MCP servers. | 861 | `test <name>` | Test connection to an MCP server. | 862 | `configure <name>` (alias: `config`) | Toggle tool selection for a server. | 863 864 See [MCP Config Reference](./mcp-config-reference.md), [Use MCP with Hermes](../guides/use-mcp-with-hermes.md), and [MCP Server Mode](../user-guide/features/mcp.md#running-hermes-as-an-mcp-server). 865 866 ## `hermes plugins` 867 868 ```bash 869 hermes plugins [subcommand] 870 ``` 871 872 Unified plugin management — general plugins, memory providers, and context engines in one place. Running `hermes plugins` with no subcommand opens a composite interactive screen with two sections: 873 874 - **General Plugins** — multi-select checkboxes to enable/disable installed plugins 875 - **Provider Plugins** — single-select configuration for Memory Provider and Context Engine. Press ENTER on a category to open a radio picker. 876 877 | Subcommand | Description | 878 |------------|-------------| 879 | *(none)* | Composite interactive UI — general plugin toggles + provider plugin configuration. | 880 | `install <identifier> [--force]` | Install a plugin from a Git URL or `owner/repo`. | 881 | `update <name>` | Pull latest changes for an installed plugin. | 882 | `remove <name>` (aliases: `rm`, `uninstall`) | Remove an installed plugin. | 883 | `enable <name>` | Enable a disabled plugin. | 884 | `disable <name>` | Disable a plugin without removing it. | 885 | `list` (alias: `ls`) | List installed plugins with enabled/disabled status. | 886 887 Provider plugin selections are saved to `config.yaml`: 888 - `memory.provider` — active memory provider (empty = built-in only) 889 - `context.engine` — active context engine (`"compressor"` = built-in default) 890 891 General plugin disabled list is stored in `config.yaml` under `plugins.disabled`. 892 893 See [Plugins](../user-guide/features/plugins.md) and [Build a Hermes Plugin](../guides/build-a-hermes-plugin.md). 894 895 ## `hermes tools` 896 897 ```bash 898 hermes tools [--summary] 899 ``` 900 901 | Option | Description | 902 |--------|-------------| 903 | `--summary` | Print the current enabled-tools summary and exit. | 904 905 Without `--summary`, this launches the interactive per-platform tool configuration UI. 906 907 ## `hermes sessions` 908 909 ```bash 910 hermes sessions <subcommand> 911 ``` 912 913 Subcommands: 914 915 | Subcommand | Description | 916 |------------|-------------| 917 | `list` | List recent sessions. | 918 | `browse` | Interactive session picker with search and resume. | 919 | `export <output> [--session-id ID]` | Export sessions to JSONL. | 920 | `delete <session-id>` | Delete one session. | 921 | `prune` | Delete old sessions. | 922 | `stats` | Show session-store statistics. | 923 | `rename <session-id> <title>` | Set or change a session title. | 924 925 ## `hermes insights` 926 927 ```bash 928 hermes insights [--days N] [--source platform] 929 ``` 930 931 | Option | Description | 932 |--------|-------------| 933 | `--days <n>` | Analyze the last `n` days (default: 30). | 934 | `--source <platform>` | Filter by source such as `cli`, `telegram`, or `discord`. | 935 936 ## `hermes claw` 937 938 ```bash 939 hermes claw migrate [options] 940 ``` 941 942 Migrate your OpenClaw setup to Hermes. Reads from `~/.openclaw` (or a custom path) and writes to `~/.hermes`. Automatically detects legacy directory names (`~/.clawdbot`, `~/.moltbot`) and config filenames (`clawdbot.json`, `moltbot.json`). 943 944 | Option | Description | 945 |--------|-------------| 946 | `--dry-run` | Preview what would be migrated without writing anything. | 947 | `--preset <name>` | Migration preset: `full` (all compatible settings) or `user-data` (excludes infrastructure config). Neither preset imports secrets — pass `--migrate-secrets` explicitly. | 948 | `--overwrite` | Overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts). | 949 | `--migrate-secrets` | Include API keys in migration. Required even under `--preset full`. | 950 | `--no-backup` | Skip the pre-migration zip snapshot of `~/.hermes/` (by default a single restore-point archive is written to `~/.hermes/backups/pre-migration-*.zip` before apply; restorable with `hermes import`). | 951 | `--source <path>` | Custom OpenClaw directory (default: `~/.openclaw`). | 952 | `--workspace-target <path>` | Target directory for workspace instructions (AGENTS.md). | 953 | `--skill-conflict <mode>` | Handle skill name collisions: `skip` (default), `overwrite`, or `rename`. | 954 | `--yes` | Skip the confirmation prompt. | 955 956 ### What gets migrated 957 958 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. 959 960 **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. 961 962 **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. 963 964 **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. 965 966 For the complete config key mapping, SecretRef handling details, and post-migration checklist, see the **[full migration guide](../guides/migrate-from-openclaw.md)**. 967 968 ### Examples 969 970 ```bash 971 # Preview what would be migrated 972 hermes claw migrate --dry-run 973 974 # Full migration (all compatible settings, no secrets) 975 hermes claw migrate --preset full 976 977 # Full migration including API keys 978 hermes claw migrate --preset full --migrate-secrets 979 980 # Migrate user data only (no secrets), overwrite conflicts 981 hermes claw migrate --preset user-data --overwrite 982 983 # Migrate from a custom OpenClaw path 984 hermes claw migrate --source /home/user/old-openclaw 985 ``` 986 987 ## `hermes dashboard` 988 989 ```bash 990 hermes dashboard [options] 991 ``` 992 993 Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. Requires `pip install hermes-agent[web]` (FastAPI + Uvicorn). See [Web Dashboard](/docs/user-guide/features/web-dashboard) for full documentation. 994 995 | Option | Default | Description | 996 |--------|---------|-------------| 997 | `--port` | `9119` | Port to run the web server on | 998 | `--host` | `127.0.0.1` | Bind address | 999 | `--no-open` | — | Don't auto-open the browser | 1000 1001 ```bash 1002 # Default — opens browser to http://127.0.0.1:9119 1003 hermes dashboard 1004 1005 # Custom port, no browser 1006 hermes dashboard --port 8080 --no-open 1007 ``` 1008 1009 ## `hermes profile` 1010 1011 ```bash 1012 hermes profile <subcommand> 1013 ``` 1014 1015 Manage profiles — multiple isolated Hermes instances, each with its own config, sessions, skills, and home directory. 1016 1017 | Subcommand | Description | 1018 |------------|-------------| 1019 | `list` | List all profiles. | 1020 | `use <name>` | Set a sticky default profile. | 1021 | `create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]` | Create a new profile. `--clone` copies config, `.env`, and `SOUL.md` from the active profile. `--clone-all` copies all state. `--clone-from` specifies a source profile. | 1022 | `delete <name> [-y]` | Delete a profile. | 1023 | `show <name>` | Show profile details (home directory, config, etc.). | 1024 | `alias <name> [--remove] [--name NAME]` | Manage wrapper scripts for quick profile access. | 1025 | `rename <old> <new>` | Rename a profile. | 1026 | `export <name> [-o FILE]` | Export a profile to a `.tar.gz` archive. | 1027 | `import <archive> [--name NAME]` | Import a profile from a `.tar.gz` archive. | 1028 1029 Examples: 1030 1031 ```bash 1032 hermes profile list 1033 hermes profile create work --clone 1034 hermes profile use work 1035 hermes profile alias work --name h-work 1036 hermes profile export work -o work-backup.tar.gz 1037 hermes profile import work-backup.tar.gz --name restored 1038 hermes -p work chat -q "Hello from work profile" 1039 ``` 1040 1041 ## `hermes completion` 1042 1043 ```bash 1044 hermes completion [bash|zsh|fish] 1045 ``` 1046 1047 Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Hermes commands, subcommands, and profile names. 1048 1049 Examples: 1050 1051 ```bash 1052 # Bash 1053 hermes completion bash >> ~/.bashrc 1054 1055 # Zsh 1056 hermes completion zsh >> ~/.zshrc 1057 1058 # Fish 1059 hermes completion fish > ~/.config/fish/completions/hermes.fish 1060 ``` 1061 1062 ## `hermes update` 1063 1064 ```bash 1065 hermes update [--check] [--backup] [--restart-gateway] 1066 ``` 1067 1068 Pulls the latest `hermes-agent` code and reinstalls dependencies in your venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install. 1069 1070 | Option | Description | 1071 |--------|-------------| 1072 | `--check` | Print the current commit and the latest `origin/main` commit side by side, and exit 0 if in sync or 1 if behind. Does not pull, install, or restart anything. | 1073 | `--backup` | Create a labeled pre-update snapshot of `HERMES_HOME` (config, auth, sessions, skills, pairing data) before pulling. Default is **off** — the previous always-backup behavior was adding minutes to every update on large homes. Flip it on permanently via `update.backup: true` in `config.yaml`. | 1074 | `--restart-gateway` | After a successful update, restart the running gateway service. Implies `--all` semantics if multiple profiles are installed. | 1075 1076 Additional behavior: 1077 1078 - **Pairing data snapshot.** Even when `--backup` is off, `hermes update` takes a lightweight snapshot of `~/.hermes/pairing/` and the Feishu comment rules before `git pull`. You can roll it back with `hermes backup restore --state pre-update` if a pull rewrites a file you were editing. 1079 - **Legacy `hermes.service` warning.** If Hermes detects a pre-rename `hermes.service` systemd unit (instead of the current `hermes-gateway.service`), it prints a one-time migration hint so you can avoid flap-loop issues. 1080 - **Exit codes.** `0` on success, `1` on pull/install/post-install errors, `2` on unexpected working-tree changes that block `git pull`. 1081 1082 ## `hermes fallback` 1083 1084 ```bash 1085 hermes fallback # interactive manager 1086 ``` 1087 1088 Manage the fallback provider chain (used when your primary provider hits a rate limit or returns a fatal error) without hand-editing `config.yaml`. Reuses the provider picker from `hermes model` — same provider list, same credential prompts, same validation. 1089 1090 Typical session: 1091 1092 1. Press `a` to add a fallback → pick a provider (OAuth-based providers open a browser; API-key providers prompt for the key), then pick the specific model. 1093 2. Use `↑`/`↓` to reorder fallbacks (first-in-list is tried first). 1094 3. Press `d` to remove one. 1095 1096 All changes persist to `fallback_providers:` under `model:` in `config.yaml`. Interacts with [Credential Pools](/docs/user-guide/features/credential-pools): pools rotate keys *within* a provider, fallbacks switch to a *different* provider entirely. 1097 1098 See [Fallback Providers](/docs/user-guide/features/fallback-providers) for behavior details and interaction with `fallback_model` (legacy single-fallback key). 1099 1100 ## Maintenance commands 1101 1102 | Command | Description | 1103 |---------|-------------| 1104 | `hermes version` | Print version information. | 1105 | `hermes update` | Pull latest changes and reinstall dependencies. | 1106 | `hermes uninstall [--full] [--yes]` | Remove Hermes, optionally deleting all config/data. | 1107 1108 ## See also 1109 1110 - [Slash Commands Reference](./slash-commands.md) 1111 - [CLI Interface](../user-guide/cli.md) 1112 - [Sessions](../user-guide/sessions.md) 1113 - [Skills System](../user-guide/features/skills.md) 1114 - [Skins & Themes](../user-guide/features/skins.md)