Hermes Agent commands and invocations, by how often they earn their keystrokes.
Interactive or one-shot chat with the agent.
Interactively choose the default provider and model.
Configure named Mixture of Agents presets selectable from the model picker.
Manage fallback providers tried when the primary model errors.
Run or manage the messaging gateway service.
Local OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy.
Outbound credential-injection firewall for remote terminal sandboxes (iron-proxy). Disabled by default. See Egress proxy.
Manage Language Server Protocol integration (semantic diagnostics for write_file/patch).
Interactive setup wizard for all or part of the configuration.
Configure and pair the WhatsApp bridge.
Configure the official Meta WhatsApp Business Cloud API adapter (Business account + public webhook required). Distinct from hermes whatsapp (Baileys personal-account bridge).
Slack helpers (currently: generate the app manifest with every command as a native slash).
Manage credentials — add, list, remove, reset, status, logout. Handles OAuth flows for Codex/Nous/Anthropic.
Send a one-shot message to a configured messaging platform (Telegram, Discord, Slack, Signal, SMS, …). Useful from shell scripts, cron jobs, CI hooks, and monitoring daemons — no…
Register peer Hermes gateways on other machines and DM their agents' canonical Bot Chats (hermes peer dm <peer>[/<agent>] "…"). The transport behind cross-machine bot-to-bot…
Manage external secret sources (currently Bitwarden Secrets Manager) for pulling API keys at process startup instead of from ~/.hermes/.env.
Diagnose and (optionally) rewrite config.yaml to replace references to retired models or deprecated settings (e.g. migrate xai).
Noninteractive counterpart of /codex-runtime: migrate [--dry-run] [--json] regenerates the Hermes-managed block in ~/.codex/config.toml for the selected profile. See Codex…
Show agent, auth, and platform status.
Show the configured account's rate-limit windows (the /usage block) without a session; --json for scripts.
Inspect and tick the cron scheduler.
Multi-profile collaboration board (tasks, links, dispatcher).
Manage named, multi-folder workspaces (projects). Anchors desktop session grouping and, when bound to a kanban board, gives tasks a deterministic worktree + branch convention…
Manage dynamic webhook subscriptions for event-driven activation.
Inspect, approve, or remove shell-script hooks declared in config.yaml.
Diagnose config and dependency issues.
On-demand supply-chain audit (OSV.dev) for the venv, plugin requirements, and pinned MCP servers.
Approval-prompt tools — mine approval history into allowlist proposals.
Copy-pasteable setup summary for support/debugging.
Show a byte breakdown of the system prompt + tool schemas (skills index, memory, profile). Runs offline.
Debug tools — upload logs and system info for support.
Back up Hermes home directory to a zip file.
Inspect / prune / clear ~/.hermes/checkpoints/ (the shadow store used by /rollback). Run with no args for a status overview.
Restore a Hermes backup from a zip file.
View, tail, and filter agent/gateway/error log files.
Show, edit, migrate, and query configuration files.
List, switch, and tweak display skins.
Open the safe Hermes command console.
Approve or revoke messaging pairing codes.
Browse, install, publish, audit, and configure skills.
Group several skills under a single /<name> slash command. See Skill Bundles.
Background skill maintenance — status, run, pause, pin. See Curator.
Configure external memory provider. Plugin-specific subcommands (e.g. hermes honcho) register automatically when their provider is active.
Run Hermes as an ACP server for editor integration.
Manage MCP server configurations and run Hermes as an MCP server.
Manage Hermes Agent plugins (install, enable, disable, remove).
Nous Portal status, subscription link, and Tool Gateway routing. See Tool Gateway.
Configure enabled tools per platform.
Install or check the Computer Use (cua-driver) backend (macOS/Windows/Linux).
Browse, install, and select petdex animated pets shown across the CLI, TUI, and desktop app. Subcommands: list, install, select, show, off, scale, remove, doctor.
Browse, export, prune, rename, and delete sessions.
Show token/cost/activity analytics.
OpenClaw migration helpers.
Import a Claude Code (~/.claude) or Codex CLI (~/.codex) setup.
Launch the web dashboard for managing config, API keys, and sessions.
Start the Hermes backend server (headless; powers the desktop app and remote backends).
Manage profiles — multiple isolated Hermes instances.
Print shell completion scripts (bash/zsh/fish).
Show version information.
Pull latest code and reinstall dependencies. --check previews without installing; --backup takes a pre-pull HERMES_HOME snapshot.
Remove Hermes from the system.
subtype: "init", model, session_id
text — a streamed assistant text delta
name; input when the tool arguments are available
name, output (capped at 5000 chars), duration_ms, is_error
session_id, exit_code, text, tokens (input, output, total, cache_read, cache_write), duration_ms; error when the turn failed
Run the gateway in the foreground. Recommended for WSL, Docker, and Termux.
Start the installed systemd/launchd background service.
Stop the service (or foreground process).
Restart the service.
Show service status.
List all profiles and whether each profile's gateway is currently running (with PID where available). Handy when you run multiple profiles side-by-side and want a single overview.
Install as a systemd (Linux) or launchd (macOS) background service.
Remove the installed service.
Interactive messaging-platform setup.
Fold per-profile standalone gateways onto the one host gateway (--multiplex, the only mode — hermes update runs it automatically unless a real boundary blocks it). Re-running it…
Remove legacy hermes.service units left over from pre-rename installs. Profile units (hermes-gateway-<profile>.service) and unrelated services are never touched. Flags: --dry-run…
Eagerly install one server's binary.
Install every server with a known auto-install recipe.
Print the resolved binary path for one server.
Provider and model setup.
Terminal backend and sandbox setup.
Messaging platform setup.
Enable/disable tools per platform.
Open portal.nousresearch.com/manage-subscription in your default browser.
Message the peer agent's canonical Bot Chat and print the reply (--json for machine-readable output; message falls back to stdin).
Start a long canonical Bot Chat turn asynchronously and return its run_id, session ID, and idempotency key (--json supported). Reuse --idempotency-key when retrying the same…
Poll an asynchronous peer run and print its final output when complete (--json supported).
Stop the exact asynchronous peer run without targeting another turn (--json supported).
Remove a peer from the registry (the .env key entry is left in place).
Rotate the access token: validates the new token against Bitwarden before storing it in .env (a rejected token changes nothing). Accepts --access-token for non-interactive use and…
Fetch secrets now and report what changed. Add --apply to actually export the secrets into the current shell's environment (default is dry-run).
Turn off the Bitwarden integration.
List available proxy upstream providers.
Run a one-shot supply-chain audit.
Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports --clear-skills, --add-skill, and --remove-skill, plus --reasoning-effort (empty string…
Pause a job without deleting it.
Resume a paused job. A recurring slot that came due while paused stays due (one catch-up run or a logged skip on the next tick); otherwise the next future run is computed.
Delete a scheduled job.
Read-only fleet health check: failed runs, failed deliveries, overdue/missing next_run_at, missing scripts or workdirs. Exits non-zero when issues are found.
Run due jobs once and exit.
Create kanban.db if missing. Idempotent.
Create a new board. Flags: --name, --description, --icon, --color, --switch (make active). Slug is kebab-case, auto-downcased.
Change a board's display name. Slug is immutable.
Archive (default) or hard-delete a board. --delete skips the archive step. Archived boards move to boards/_archived/<slug>-<ts>/. Refused for default.
Create a new task on the active board. Flags: --body, --assignee, --parent (repeatable), --workspace scratch|worktree|dir:<path>, --tenant, --priority, --triage…
Show a task with comments and events. --json for machine output.
Assign or reassign. Use none to unassign. Refused while task is running.
Add a dependency. Cycle-detected. Both tasks must be on the same board.
Remove a dependency.
Atomically claim a ready task. Prints resolved workspace path.
Append a comment. The next worker that claims the task reads it as part of its kanban_show() response.
Mark task done. Flags: --result, --summary, --metadata.
Mark task blocked for human input. Also appends the reason as a comment.
Move a task to review with a reviewer handoff — NOT a block. Flags: --summary, --metadata, --reviewer (reassigns before review dispatch).
Reviewer verdict for an active review run: close the review attempt and route the task back to its original implementer.
Send review task(s) back for changes (review → ready/todo). Flag: --reason (appended as a comment).
Park time-delay/follow-up work in scheduled so it is not shown as a human blocker.
Restore a blocked task to its source phase (review or ready), or todo while dependencies remain open.
Hide from default list. gc will remove scratch workspaces.
Follow a task's event stream.
One dispatcher pass on the active board. Flags: --dry-run, --max N, --failure-limit N, --json.
Print the full context a worker would see (title + body + parent results + comments).
Remove scratch workspaces for archived tasks.
Create a new project.
Show a project's details.
Add a folder / repo to a project.
Remove a folder from a project.
Rename a project.
Set the primary folder.
Set the active project.
Archive a project (recoverable).
Restore an archived project.
Bind a kanban board to this project.
Send a test POST to verify a subscription is working.
Force a cleanup sweep — delete orphan and stale projects, GC the store, enforce the size cap. Ignores the 24h idempotency marker.
Delete the entire checkpoint base. Irreversible; asks for confirmation unless -f.
Delete only the legacy-<timestamp>/ archives produced by the v1→v2 migration. Exits 2 (after printing Could not delete N archive(s)) when any archive could not be removed, e.g…
Which log to view: agent (default), errors, gateway, or list to show available files with sizes.
Print the .env file path.
Approve a pairing code.
Revoke a user's access.
Clear pending pairing codes.
Paginated browser for skill registries.
Search skill registries.
Preview a skill without installing it.
Reinstall hub skills with upstream changes when available.
Stop bundled skills from being seeded into the active profile. Writes a .no-bundled-skills marker so the installer, hermes update, and any sync skip bundled-skill seeding. Safe by…
Undo opt-out by removing the .no-bundled-skills marker so bundled skills are seeded again on the next hermes update. With --sync, re-seed immediately.
Publish a skill to a registry.
Manage custom skill sources.
Show one bundle's name, description, skills, and file path
Create a new bundle. Pass --skill <id> (repeat) or omit for interactive entry. --description, --instruction, --force available.
Remove a bundle file
Re-scan ~/.hermes/skill-bundles/ and report added/removed bundles
Start the LLM pass in a background thread and return immediately
Preview only — produce the review report with no mutations
Take a manual tar.gz snapshot of ~/.hermes/skills/ (curator also snapshots automatically before every real run)
Restore ~/.hermes/skills/ from a snapshot (defaults to newest)
List available snapshots
Restore a specific snapshot by id
Skip the confirmation prompt
Pin a skill so the curator never auto-transitions it
Restore an archived skill
Archive a skill manually
List archived skills (recoverable via restore)
Pick a provider + model (same picker as hermes model) and append to the chain
Fire every hook matching <event> against a synthetic payload
Disable external provider (built-in only).
List Nous-approved MCPs (plain text, scriptable).
Install a catalog entry (e.g. hermes mcp install deepwiki).
Run Hermes as an MCP server — expose conversations to other agents.
Test connection to an MCP server.
Install a plugin from the Hermes plugin catalog (bare entry name), a Git URL, or owner/repo shorthand. Catalog names resolve to the entry's repo at its pinned 40-hex commit SHA…
Search the Hermes plugin catalog (matches entry names, descriptions, and declared tools; omit term to list everything). The catalog is curated in-repo (plugin-catalog/), refreshed…
Pull latest changes for an unpinned installed plugin. Pinned plugins must be reinstalled with --force --ref <new-commit> to move.
Enable a disabled plugin.
Disable a plugin without removing it.
Validate a native plugin through the real manifest parser, loader, and registration path. --ci exits 1 on errors.
Install a plugin pack (hermes-pack.yaml) — a declarative set of plugins each pinned to an exact 40-character commit SHA. Shows a mandatory review screen (every plugin, source…
Dry-run: parse, validate, and display a pack without installing anything.
Re-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade.
Run cua-driver's health report and show its platform checks.
Report macOS Accessibility and Screen Recording grants.
Ask macOS to grant Accessibility and Screen Recording to Cua Driver.
Set the active pet (writes display.pet.*).
Resize the pet everywhere (display.pet.scale).
Export sessions to JSONL.
Delete one session.
Show session-store statistics.
Set or change a session title.
Reclaim disk space: merge FTS5 index segments + VACUUM. Non-destructive — no session data changes.
Migrate the full-text search index to the compact v23 external-content layout; on large databases this reclaims a large fraction of state.db.
Repair a malformed state.db schema (e.g. table messages_fts already exists) so hidden sessions reappear; a backup is made first.
Re-attach gateway conversations stranded in session rows that lost their routing identity (a chat "jumping back in time" after a restart). Dry-run by default; --apply performs the…
Settle session, routing, Telegram-topic and voice-mode state that landed under the wrong profile (rows in another profile's store, labels disagreeing with the session key, parent…
Offline, non-destructive recovery of a damaged state.db into a separate clean database.
Regenerate titles for sessions opened with a /skill, using what the user actually typed; lists changes unless --apply is passed.
Set a sticky default profile.
Delete a profile.
Manage wrapper scripts for quick profile access.
Rename a profile.
Export a profile to a .tar.gz archive (local backup).
Import a profile from a .tar.gz archive (local restore).
Install a profile distribution from a git URL or local directory.
Show a profile's distribution manifest (version, requirements, source).
The install also ships hermes-agent, a minimal runner that sends one query and exits: hermes-agent --query "summarize README.md" (or hermes-agent "summarize README.md")…
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…
--file is for text bodies only. To deliver an image, document, video, or audio file as a native platform attachment, reference it inside the message text with the…
On-demand vulnerability scan against OSV.dev. Covers the Hermes venv (installed PyPI distributions), Python dependencies declared by plugins under ~/.hermes/plugins/, and pinned…
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.
Subscriptions persist to ~/.hermes/webhook_subscriptions.json and are hot-reloaded by the webhook adapter without a gateway restart. Re-running subscribe for an existing name…
hermes dump is specifically designed for sharing. For interactive diagnostics, use hermes doctor. For a visual overview, use hermes status.
See Checkpoints and /rollback for the full architecture and the in-session commands.
.db members (state.db, kanban.db, response_store.db, …) are not published with a rename like ordinary files. Renaming would replace the file's inode while a gateway, dashboard, or…
Filters can be combined. When multiple filters are active, a log line must pass all of them to be shown:
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…
Register this install as a self-hosted dashboard with your Nous Portal account. Creates an OAuth client, writes HERMES_DASHBOARD_OAUTH_CLIENT_ID into ~/.hermes/.env, and prints…
Switch between already-configured models without leaving a session:
Common failure modes + recovery are covered in Egress proxy → Troubleshooting.
Onchain AI Garage put together a Masterclass walkthrough of installation, setup, and basic commands - a good companion to this page if you'd rather follow along on video.
Brand new and want the shortest path to a working setup Switching providers and don't want to lose time to config mistakes Setting up Hermes for a team, bot, or always-on workflow…
Pick the row that matches your goal: Goal Do this first Then do this I just want Hermes working on my machine hermes setup Run a real chat and verify it responds I already know my…
Run in powershell: After it finishes, reload your shell: For detailed installation options, prerequisites, and troubleshooting, see the Installation guide .
Hermes separates secrets from normal config: Secrets and tokens → ~/.hermes/.env Non-secret settings → ~/.hermes/config.yaml The easiest way to set values correctly is through the…
Connect Telegram , Discord , Slack , WhatsApp , Signal , Email , or Home Assistant , or Microsoft Teams .
For safety, run the agent in a Docker container or on a remote server: For Docker sandboxes, you can also enable the egress credential-injection proxy so the sandbox never sees…
Skills are on-demand instruction documents that teach Hermes how to do a specific task - deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs.
ACP support ships with the standard [all] extras, so the curl installer already includes it.
These are the problems that waste the most time: Symptom Likely cause Fix Hermes opens but gives empty or broken replies Provider auth or model selection is wrong Run hermes model…
Download the package for your platform from the Hermes website .
The scripts clone the source, bootstrap uv, and delegate dependency preparation to PM.
Reload your shell and start chatting: To reconfigure individual settings later, use the dedicated commands: Fastest path: Nous Portal One subscription covers 300+ models plus the…
For a source checkout, start with the PM developer workflow .
Run the source installer as the intended service user.
Hermes supports a symlinked HERMES_HOME and symlinked home subdirectories, including hooks , skills , sessions , and logs .
The update owner depends on the running installation, not only its data home.
hermes -w sessions create disposable worktrees under <repo>/.worktrees/ .
The hermes plugins commands manage native Hermes plugins and portable Agent Plugins v1 packages through the same opt-in workflow: Portable packages remain disabled until…
A persistent status bar sits above the input area, updating in real time: Element Description Model name Current model (truncated if longer than 26 chars) Token count Context…
When resuming a previous session ( hermes -c or hermes --resume <id> ), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of…
to run it as a shell command instead of sending it to the agent: Zero cost.
You can define custom commands that run shell commands instantly without invoking the LLM.
If you already know which skills you want active for the session, pass them at launch time: Hermes loads each named skill into the session prompt before the first turn.
To have the same skills active at the start of every new session - CLI, TUI, gateway, cron and API sessions alike - set skills.auto_load in config.yaml : Each entry is a skill…
Every installed skill in ~/.hermes/skills/ is automatically registered as a slash command.
Set a predefined personality to change the agent's tone: Built-in personalities include: helpful , concise , technical , creative , teacher , kawaii , catgirl , pirate …
While the agent is working, you can send a correction without starting a new turn: Type a new message + Enter - redirects the active turn using your correction Ctrl+C - interrupt…
The display.busy_input_mode config key controls what happens when you press Enter while the agent is working: Mode Behavior "interrupt" (default) Your message redirects the active…
On Unix systems, press Ctrl+Z to suspend Hermes to the background - just like any terminal process.
The CLI shows animated feedback as the agent works: Thinking animation (during API calls): Tool execution feed: Cycle through display modes with /verbose : off → new → all →…
The display.tool_preview_length config key controls the maximum number of characters shown in tool call preview lines (e.g.
When you exit a CLI session, a resume command is printed: Resume options: Resuming restores the full conversation history from SQLite.
Long conversations are automatically summarized when approaching context limits: When compression triggers, middle turns are summarized while the first 3 and last 20 turns are…
Run a prompt in a separate background session while continuing to use the CLI for other work: Hermes immediately confirms the task and gives you back the prompt:
Each /bg prompt spawns a completely separate agent session in a daemon thread: Isolated conversation - the background agent has no knowledge of your current session's history.
When a background task finishes, the result appears as a panel in your terminal: If the task fails, you'll see an error notification instead.
By default, the CLI runs in quiet mode which: Suppresses verbose logging from tools Enables kawaii-style animated feedback Keeps output clean and user-friendly For debug output…
Use the documented recipe to send or pipe a result through Hermes.
Use the documented recipe to check delivery results in a shell script.
Use the documented recipe to discover configured message destinations.
Use the documented recipe to report a build result to a team channel.
Use the documented recipe to send a resource alert from a watchdog.
Use the documented recipe to create a script-only watchdog from the CLI.
Use the documented recipe to schedule the documented disk-space alert.
Use the documented recipe to manage the lifecycle of a script-only job.
Use the documented recipe to inspect and approve staged memory writes.
Use the documented recipe to inspect and approve a pending skill diff.
Use the documented recipe to search installed skills by topic.
Use the documented recipe to load a namespaced plugin skill explicitly.
Use the documented recipe to inspect the configuration needed by a skill.
Use the documented recipe to exercise a newly written skill in a fresh session.
Use the documented recipe to start Hermes as an MCP server.
Use the documented recipe to reload MCP connections after editing configuration.
Use the documented recipe to install an official optional skill from the Hub.
Use the documented recipe to test and pause a scheduled workflow.
Use the documented recipe to inspect a running gateway and its logs.
Use the documented recipe to pair a new team member with the bot.
Type / to see the autocomplete dropdown.
There are two ways to enter multi-line messages: Alt+Enter , Ctrl+J , or Shift+Enter - inserts a new line Backslash continuation - end a line with \ to continue: Ctrl+J and…
display.cli_layout picks how the classic CLI draws.