Command-line product
Hermes is a command-line control plane for an AI agent and its surrounding services. It gives an engineer one place to install and configure Hermes, start agent work, select an isolated profile, connect external platforms, and keep the running system healthy.
Control plane role
The command line joins user intent to the main Hermes services. It can start a local agent session, manage a long-running gateway, change the active configuration, or perform an install and update operation. The command line is therefore both a user interface and an operations surface.
The main entry point is home/…/main.py. It selects a command, applies the requested profile, and hands the work to the relevant product area. A command with no subcommand starts chat, while named commands cover setup, gateway control, profiles, integrations, diagnostics, and maintenance.
The high-level relationship is:
flowchart LR
Engineer[Engineer or script] --> CLI[Hermes command line]
CLI --> Config[Profile configuration]
CLI --> Chat[Agent session]
CLI --> Gateway[Gateway and platform services]
CLI --> Maintenance[Install, update, backup, repair]
Chat --> Result[Agent result]
Gateway --> Result
Maintenance --> Healthy[Healthy Hermes installation]
Command surface
The command surface has two related forms. Top-level commands operate from the shell and manage Hermes as a product. An interactive session adds slash commands for actions that belong inside a conversation, such as changing the model, inspecting status, or starting background work.
The shell command families group by outcome rather than by internal module:
| Command family | Product purpose |
|---|---|
chat and the default command | Start an interactive, TUI, or scripted agent session. |
setup, model, auth, config, and tools | Make the agent ready to run and control its behavior. |
profile and sessions | Separate workspaces and return to earlier work. |
gateway, send, pairing, and platform commands | Connect Hermes to messaging and external services. |
dashboard, serve, and acp | Expose Hermes to local or editor-facing interfaces. |
status, doctor, logs, backup, update, and uninstall | Inspect, maintain, repair, or remove the installation. |
The command tree is assembled by home/…/main.py and each command owns a clear product action. This keeps the command line useful for both direct human work and automation without making scripts depend on terminal display text.
Setup and configuration
Setup turns a fresh Hermes installation into a usable agent. It gathers provider and model access, terminal behavior, agent options, tools, and messaging choices. The same control plane also supports smaller changes after first use, so an engineer can adjust one area without repeating the full setup path.
The setup path is designed for two operating modes:
- An interactive wizard for a person at a terminal.
- Non-interactive configuration through environment values and configuration commands for scripts or headless hosts.
The setup wizard can also establish the Nous Portal connection as one focused action. Provider selection and authentication then become shared inputs for chat, gateway work, and other integrations instead of separate per-command state.
See CLI setup and configuration for the setup lifecycle, configuration sources, provider selection, and managed runtime setup.
References: hermes_cli/setup.py• L1-6 hermes_cli/setup.py• L77-98 hermes_cli/…/setup.py• L8-38 hermes_cli/main.py• L1662-1692
Interactive use
Interactive use is the primary path for asking Hermes to perform work. The command line can open the classic terminal prompt or the TUI, accept a single request for automation, and resume a stored session when work continues later. The interface keeps the agent result, tool activity, model choice, and session controls in one place.
The session surface supports both short tasks and long work. A person can redirect or stop active work, change session-level settings, load skills, and use background tasks without leaving Hermes. A script can use a one-shot command and consume a stable result or structured output instead of a human-oriented screen.
See CLI sessions and platform operations for session behavior, TUI and chat paths, profile commands, dashboards, and user-facing operations.
References: cli.py• L889-919 cli.py• L1131-1153 hermes_cli/main.py• L1734-1815 website/…/cli.md• L7-18 website/…/cli.md• L475-516
Profiles and integrations
A Hermes profile is an isolated operating context for one use case. It has its own configuration, credentials, skills, memory, sessions, and gateway identity. Profiles let one installation serve different agents or workspaces without mixing their state.
The command line selects a profile before the command runs. The active profile can be chosen for one invocation or set as the sticky default. A gateway can serve the default profile and live named profiles together, while a profile can also opt out when it needs its own gateway boundary. This makes profile selection part of routing and service ownership, not only a display preference.
Integrations use the same control plane. Hermes can configure and operate messaging gateways, send one-shot messages, manage authentication, connect MCP or editor clients, and expose a dashboard or local service. These operations share the selected profile so that credentials, sessions, and platform state stay aligned.
See CLI sessions and platform operations for platform enrollment, dashboards, messaging controls, and profile-facing commands.
References: hermes_cli/main.py• L427-665 hermes_cli/…/profile.py• L8-164 hermes_cli/profiles.py• L1174-1197 hermes_cli/main.py• L3383-3459 hermes_cli/gateway.py• L1-3
Installation and lifecycle
The command line also owns the Hermes lifecycle. Installation establishes the executable environment and its managed dependencies. Update moves that installation to a newer release, coordinates the services that use it, and reports work that still needs attention. Backup, import, diagnostics, logs, and repair provide paths when the normal lifecycle is interrupted or the installation is not healthy.
Lifecycle actions protect the boundary between code and live state. User profiles and credentials must remain available while code changes. Running gateways must be restarted with the updated code, and an update must distinguish a refused operation from an operation that changed code but still needs service follow-up.
See Installation, update, and recovery for installation ownership, release channels, staged updates, service coordination, backups, diagnostics, and recovery.
References: hermes_cli/…/update.py• L8-114 hermes_cli/main.py• L2393-2447 website/…/cli-internals.md• L11-82 hermes_cli/main.py• L3427-3458
Change checklist
When these files or sections are changed, remember to consider these:
- A new shell command must connect parser registration, command dispatch, help output, profile selection, and any automation-facing exit or output contract.
- A new configuration value must be readable by every surface that needs it. CLI, gateway, and profile-scoped readers must agree on its source and precedence.
- A provider or platform change must keep setup, stored credentials, gateway startup, status reporting, and one-shot delivery aligned.
- A profile change must preserve the link between the selected
HERMES_HOME, profile state, gateway serving set, and session identity. - An update change must account for every live profile and service that can still run the old code. The update receipt and follow-up state must describe any unfinished restart or verification work.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Chat starts with no configured provider and no interactive terminal | Hermes cannot start the agent and exits with setup guidance. | First-run setup checks provider readiness before launching chat and provides non-interactive configuration guidance. |
| A command selects a missing or invalid profile | The command cannot safely resolve its configuration and state. | Profile names are normalized and checked before HERMES_HOME is applied. |
| A platform is configured but its gateway is stopped or attached to another profile | Inbound events do not reach the intended agent, or messages use the wrong credentials. | Gateway and profile operations report service ownership and use profile-scoped state. |
| Two lifecycle operations mutate the same installation at once | The checkout or managed environment can become inconsistent. | Update admission and a shared update lock refuse concurrent mutation. |
| Code update completes but a service restart or verification fails | The installation has new code while one or more services may still run old code. | Fleet restart, version verification, receipts, and owed follow-ups keep the unfinished work visible for retry. |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/main.py | Shows the top-level command tree, profile selection, chat launch, and lifecycle dispatch. |
| cli.py | Shows the classic interactive session surface and its slash-command control model. |
| hermes_cli/setup.py | Shows the product goals and entry points of the setup wizard. |
| hermes_cli/profiles.py | Shows profile identity, isolation, and the set of profiles a gateway can serve. |
| hermes_cli/gateway.py | Shows how the command line treats gateway processes and service control. |
| hermes_cli/…/update.py | Shows the user-facing contract for checking, planning, and applying updates. |
| website/…/cli.md | Gives the user-level view of interactive CLI capabilities and session controls. |
| website/…/cli-internals.md | Records the lifecycle and profile contracts that span the command line and running services. |