CLI sessions and platform operations
Hermes provides one command-line product with several user-facing ways to start work, continue a conversation, connect messaging channels, and operate the local agent. The classic CLI, terminal UI (TUI), web dashboard, profiles, session store, gateway, and platform controls work together so a user can move between local and remote conversations without losing the session context. This page extends Command-line product with operational flows; see CLI setup and configuration and CLI installation, update, and recovery for adjacent lifecycle topics.
Interactive chat surfaces
The interactive surfaces turn a user prompt into a session-backed agent conversation. The classic CLI is the default terminal path, while the TUI adds a richer terminal view and the dashboard hosts that same TUI in a browser.
Classic CLI chat
The classic CLI is a prompt-driven chat surface for interactive work and one-shot requests. hermes and hermes chat can start a new conversation, resume an existing one, select a model or provider, preload skills, and run a non-interactive query. The session is saved so the user can continue it later with --continue or --resume.
The CLI also exposes slash commands for actions that do not need a new model turn. These commands let a user inspect the session, change its model or title, control work in progress, browse sessions, and move the conversation to a messaging platform. The same command registry supplies the commands shown on supported gateway platforms, so the command vocabulary stays aligned across surfaces.
TUI launch path
The TUI is selected by an explicit --tui flag, by the HERMES_TUI=1 setting, or by the configured interface when both standard streams are real terminals. --cli forces the classic interface. Non-interactive input stays on the classic path so pipes, cron jobs, and automation do not start a terminal-only UI.
The TUI keeps the composer, transcript, live work view, approvals, model picker, session picker, and slash commands in one interactive surface. It can keep more than one live session available, while switching to a cold session protects the current turn from an unsafe mid-stream change.
The launch choice and the shared session state follow this flow:
flowchart LR
A[hermes or hermes chat] --> B{Interactive terminal?}
B -- no --> C[Classic CLI or one-shot request]
B -- yes --> D{Interface choice}
D -- --cli --> C
D -- --tui or configured TUI --> E[Terminal UI]
C --> F[Session store and gateway-backed agent]
E --> F
F --> G[Transcript, tools, approvals, and resume state]
References: hermes_cli/main.py• L1725-1815 hermes_cli/main_tui_launch.py• L500-524 hermes_cli/commands.py• L44-77
Dashboard chat
The dashboard is a browser operations surface that also embeds the TUI. Its Chat page starts the real TUI in a terminal session and streams the terminal output to the browser, so chat behavior remains consistent with hermes --tui rather than becoming a separate chat product.
The dashboard can start a new chat in a selected workspace or resume a session from its session list. A profile switch changes the model, skills, memory, and session store used by the next chat. This makes the dashboard useful for remote access while keeping profile and session boundaries visible.
References: website/…/web-dashboard.md• L44-89 website/…/web-dashboard.md• L140-165 hermes_cli/…/dashboard.py• L76-101
Session and profile operations
Sessions preserve conversation identity across launches and platforms. Profiles preserve agent identity across sessions by giving each agent its own configuration, credentials, memory, skills, gateway state, and session store.
Session lifecycle
A session is the durable conversation unit. It records the source of the conversation, its title, model context, messages, usage data, timestamps, and links to related sessions created by compression or branching. CLI sessions normally use the local SQLite store, while gateway sessions use the same durable model with routing information for their originating chat.
Users manage sessions through both shell commands and slash commands:
| Need | User-facing surface |
|---|---|
| Start fresh | /new or /reset |
| Resume | hermes --continue, hermes --resume, /resume, or /sessions |
| Find history | hermes sessions list, the session picker, or dashboard search |
| Name or organize | /title, hermes sessions rename, pin, archive |
| Preserve or share | /save or hermes sessions export |
| Remove old data | hermes sessions prune, archive, or delete |
| Reduce active context | /compress |
Resuming restores the conversation and normally returns the user to its recorded workspace. A user can override that workspace when needed. Compression reduces the active context but does not delete the stored transcript.
References: website/…/sessions.md• L9-28 website/…/sessions.md• L108-188 website/…/sessions.md• L315-392 hermes_cli/…/sessions.py• L15-130
Session switching and control
The TUI treats session switching as a live control problem. A new live session can run beside the current one, but resuming a cold session closes the current view and is guarded while a turn is active. This keeps streaming state and user input attached to the correct session.
During a turn, users can stop work, queue a follow-up, steer the next tool boundary, ask a side question, or run a background prompt in a separate session. The status bar and live work dock show enough state to distinguish the active turn from queued or background work.
References: ui-tui/…/session.ts• L191-217 ui-tui/…/session.ts• L84-123 ui-tui/…/core.ts• L687-739 ui-tui/…/useMainApp.ts• L612-691
Profile operations
A profile is an independent agent home. It lets one machine host separate assistants without mixing their settings, credentials, memories, skills, sessions, or gateway state. A profile can be selected with -p, made the sticky default with hermes profile use, or addressed through its generated command alias.
Profile commands cover the agent lifecycle:
profile createcreates a blank profile or a controlled clone.profile listandprofile showdescribe identity and gateway state.profile renamechanges a named profile identity or sets the default profile display name.profile exportandprofile importmove a profile as a shareable archive.profile deleteremoves a named profile after confirmation.profile describerecords the role that task routing can use to choose an agent.
Messaging channels are not copied by normal profile cloning. This prevents two profiles from claiming one bot credential. A user must opt in to channel copying and accept the ownership conflict risk.
References: website/…/profiles.md• L5-53 website/…/profiles.md• L176-226 website/…/profiles.md• L343-387 hermes_cli/…/profile.py• L8-164
Platform enrollment and messaging controls
The gateway connects Hermes to external messaging platforms and applies platform-specific identity, access, and delivery rules. Setup stores credentials and channel policy, while gateway commands control the running connection without requiring the user to edit files by hand.
Platform setup and enrollment
hermes setup gateway and the dashboard Channels page guide a user through platform credentials, allowlists, home channels, and enablement. A home channel is the destination used for notifications, scheduled results, and cross-platform handoff. Users can also set it from the destination chat with /sethome.
The platform catalog includes common channels such as Telegram, Discord, Slack, WhatsApp, Signal, Matrix, email, webhooks, and the API server. Plugin platforms extend the catalog without changing the core chat flow. Setup may use platform-specific onboarding, such as QR pairing for WhatsApp or bot creation for Telegram.
Self-hosted gateways that use the relay connector have a separate enrollment path. hermes gateway enroll exchanges a single-use enrollment token and the operator's identity token for gateway credentials, then stores the relay identity and delivery credentials. Managed installations do not self-enroll because the hosting system supplies those credentials.
References: hermes_cli/platforms.py• L7-67 hermes_cli/setup_platforms.py• L146-184 hermes_cli/main_platform_setup.py• L133-223 hermes_cli/gateway_enroll.py• L108-209
Messaging command controls
Messaging users can use the shared slash-command model for session and gateway actions. The command registry decides which commands are available on a gateway surface, and platform adapters publish commands in the syntax allowed by that platform.
The main user-facing controls are:
| Control | Purpose |
|---|---|
/help and /commands | Discover available commands |
/status and /profile | Inspect the current session and agent identity |
/new, /resume, and /sessions | Start or select conversations |
/stop, /pause, /approve, and /deny | Control running work and approval requests |
/sethome and /handoff | Configure delivery and move a session between surfaces |
/send or platform delivery tools | Send a message to an external target |
/platforms or dashboard Channels | Inspect channel availability and setup state |
Access checks happen before command output is sent to an unauthorized user. Pairing gives an operator a way to approve users for a channel, while allowlists provide platform-specific access limits.
References: hermes_cli/commands.py• L83-184 hermes_cli/commands_platforms.py• L24-117 tests/…/test_platform_commands.py• L23-68 tests/…/test_platform_commands.py• L135-168
Platform actions
Plugins can request a small set of actions on live platform messages, such as adding a reaction or changing a thread title. These actions are not a general bypass around gateway access: the plugin needs the named capability, the active profile must resolve to the matching adapter, and the adapter must be connected.
Each action returns a success or error result and is logged. This gives user-facing plugins a stable way to report unavailable gateways, missing consent, invalid targets, and unsupported platform actions.
References: hermes_cli/platform_actions.py• L14-29 hermes_cli/platform_actions.py• L73-175 hermes_cli/platform_actions.py• L178-203
Dashboard operations
The web dashboard is a machine-level control surface for the local Hermes installation. It combines chat, session review, profile management, channel setup, gateway control, diagnostics, and usage views behind one browser endpoint.
Dashboard scope and access
A dashboard normally binds to localhost and needs no login. A non-loopback bind engages the authentication gate and refuses to start without a configured provider. This protects the dashboard because it can read and write secrets, configuration, session data, and operational state.
One dashboard can manage many profiles. The profile switcher selects the target for configuration, chat, skills, model, and MCP actions. Gateway processes and session databases remain per-profile even though the dashboard presents them from one machine-level view.
References: website/…/web-dashboard.md• L15-42 website/…/web-dashboard.md• L44-90 website/…/web-dashboard.md• L430-432 website/…/web-dashboard.md• L634-661
Dashboard management areas
The dashboard groups user-facing operations by the object they affect:
| Area | Main purpose |
|---|---|
| Status | Show gateway health, active sessions, recent activity, and resource pressure |
| Chat | Start or resume a profile-scoped TUI conversation in the browser |
| Sessions | Search, inspect, rename, export, archive, prune, or delete sessions |
| Profiles | Create, select, describe, configure, rename, or delete agents |
| Channels | Configure, enable, test, and restart messaging platforms |
| Pairing | Approve or revoke messaging users |
| Webhooks | Create, enable, disable, and remove event routes |
| System | Run diagnostics, backups, gateway controls, memory controls, and host checks |
Changes made in the dashboard use the same underlying profile configuration and session state as the CLI. The dashboard is therefore an alternate control surface, not a second source of truth.
References: website/…/web-dashboard.md• L107-118 website/…/web-dashboard.md• L276-321 website/…/web-dashboard.md• L323-432
User-facing operational commands
Operational commands let a user inspect health, control long-running services, repair session state, and move data without entering an agent conversation. They are the shell-level companion to the dashboard's System, Sessions, Channels, and Profiles pages.
Gateway and channel operations
hermes gateway manages the long-running messaging process. Its lifecycle commands start, stop, restart, install, and report the gateway, while hermes setup gateway focuses on the credentials and channel policy that the gateway consumes. hermes pairing manages user enrollment, and hermes send targets an external channel from the command line.
The gateway can serve several profiles through one host process. Commands that act on a profile must therefore keep the profile scope explicit so a restart, credential change, or platform action cannot affect another agent.
References: hermes_cli/main.py• L1832-1838 hermes_cli/main.py• L3381-3407 hermes_cli/gateway_enroll.py• L201-243 hermes_cli/…/messaging.py• L173-205
Health and recovery operations
hermes status and hermes doctor help a user tell the difference between an unavailable service, a bad platform setup, and damaged local state. Session maintenance commands list, export, optimize, archive, prune, repair, and recover the session store. Destructive or offline operations use confirmation and refuse unsafe writes when another Hermes process owns the store.
The dashboard exposes many of the same actions as background jobs with live logs. This keeps long checks and backups out of the chat turn while still giving the operator a visible result.
References: hermes_cli/…/sessions.py• L130-220 hermes_cli/sessions_cmd.py• L100-195 hermes_cli/doctor_platform.py• L123-180 website/…/web-dashboard.md• L406-424
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the classic CLI and TUI launch precedence aligned with the non-interactive TTY guard.
- Keep session picker, resume, dashboard Chat, and
--resumebehavior aligned for profile and workspace scope. - When adding a slash command, update the shared registry and confirm its gateway visibility and platform menu limits.
- When adding a platform credential or setup path, keep CLI setup, dashboard Channels, enablement checks, and allowlist behavior aligned.
- When changing profile ownership, check gateway routing, session stores, cloned channel credentials, and dashboard profile scope together.
- When changing session-store writes, preserve the offline-operation guard used by CLI, dashboard, and gateway processes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A TUI is selected for a piped or background request | The terminal UI can exit without running the requested work | The launch path chooses the classic interface when stdin or stdout is not a TTY |
| A user resumes a cold session during an active turn | Streaming state can attach to the wrong session | TUI session switching blocks cold resume while busy; live-session creation remains separate |
| Two profiles claim the same messaging bot credential | One adapter may be parked or two gateways may fight for one bot | Normal profile clones strip channel credentials and profile listing warns about shared credentials |
| A non-loopback dashboard has no auth provider | The dashboard must not expose secrets or control APIs | The server fails closed unless a password, Nous OAuth, OIDC, or another provider is configured |
| A platform user is not authorized | The user receives pairing or access handling instead of agent command output | Authorization runs before gateway command dispatch |
Session maintenance runs while another Hermes process writes state.db | Live conversations can lose or reject state changes | Optimize, prune, repair, and journal conversion require an idle store unless explicitly forced |
| Relay enrollment runs in a managed install | Local credentials would conflict with hosted provisioning | Managed installs refuse self-enrollment and use orchestrator-provided credentials |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/main.py | Main chat dispatch and the connection between top-level commands and chat launch |
| hermes_cli/main_tui_launch.py | Interface selection rules and TUI process handoff |
| hermes_cli/commands.py | Shared slash-command contract across CLI and gateway surfaces |
| ui-tui/…/useMainApp.ts | TUI session, turn, transcript, and gateway event coordination |
| ui-tui/…/session.ts | TUI session switching, background work, model, voice, and context controls |
| hermes_cli/…/sessions.py | Shell session-management command surface |
| hermes_cli/sessions_cmd.py | Session listing, export, cleanup, repair, and recovery behavior |
| hermes_cli/…/profile.py | Profile command vocabulary and profile lifecycle options |
| hermes_cli/profile_cmd.py | Profile status, selection, cloning, and identity operations |
| hermes_cli/setup_platforms.py | Interactive channel setup and home-channel enrollment flow |
| hermes_cli/gateway_enroll.py | Self-hosted relay enrollment and credential persistence |
| hermes_cli/commands_platforms.py | Translation of shared commands into platform menus and limits |
| hermes_cli/platform_actions.py | Capability-gated plugin actions on live platform messages |
| hermes_cli/…/dashboard.py | Dashboard and headless backend launch contract |
| hermes_cli/…/messaging.py | Dashboard channel configuration, enablement, and connection status |
| hermes_cli/…/sessions.py | Dashboard session listing, search, mutation, and safety guards |
| website/…/web-dashboard.md | Product-level dashboard behavior and operator workflow |
| website/…/sessions.md | Product-level session persistence, resume, search, and handoff behavior |
| website/…/profiles.md | Product-level profile isolation, cloning, and gateway ownership |