Setup & CLI Commands

Relevant source files

The following files were used as context for generating this wiki page:

• skills/autonomous-ai-agents/hermes-agent/SKILL.md
• skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
• agent/learn_prompt.py
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md

Hermes Agent provides a unified command-line interface (CLI) to manage installation, configuration, model selection, and autonomous task execution. The system runs as a multi-surface agent framework, supporting terminal interaction (TUI), native desktop applications, and messaging gateways.

The CLI acts as the primary entry point for users to initialize the environment, rotate credential pools, and manage persistent agent sessions.

Installation and Initial Setup

Installation utilizes a shell script that bootstraps the Package Manager (PM), Python environment, and dependencies. Users trigger the installation via a curl command to download and execute install.sh.

# Install (shell installer)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:32-33

Core Configuration Files

Hermes organizes configuration into two primary files to separate general settings from sensitive credentials:

1. config.yaml: Stores main configuration settings like display preferences, toolsets, and model defaults.
2. .env: Contains API keys and secrets only.

These files reside in ~/.hermes/ by default. If the HERMES_HOME environment variable is set, the system resolves all configuration and state paths relative to that directory.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:46-48, skills/autonomous-ai-agents/hermes-agent/SKILL.md:57-58

Lifecycle Flow

The following diagram illustrates the initialization and configuration flow when a user sets up Hermes for the first time:

CLI Commands Reference

The CLI is structured with several subcommands to handle different aspects of the agent's operation.

Primary Commands

Command	Description
hermes	Starts interactive chat (default surface).
hermes chat -q "<query>"	Executes a single query and returns the response.
hermes setup	Launches the setup wizard for initial configuration.
hermes model	Configures the preferred LLM provider and model.
hermes doctor	Performs a health check on the environment and credentials.
hermes desktop	Launches the native Electron desktop application (alias: hermes gui).
hermes dashboard	Opens the web admin panel and embedded chat.
hermes proxy	Starts an OpenAI-compatible local proxy.

Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:32-44

Session Management

Hermes tracks sessions in a SQLite database (state.db) with FTS5 support.

• Continue Last Session: hermes -c or hermes --continue resumes the most recent conversation.
• Resume Specific Session: hermes -r "<title/ID>" or hermes --resume <ID> restores a specific session.
• List Sessions: hermes sessions list displays previous interactions.

Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md:39-42, skills/autonomous-ai-agents/hermes-agent/SKILL.md:104-108

Internal Architecture and Command Dispatch

The CLI entry point is defined in hermes_cli/main.py, which utilizes argparse to route commands to their respective handlers.

Command Dispatch Logic

The system uses a central registry for slash commands and CLI subcommands to ensure consistency across surfaces (CLI, Slack, Telegram).

Key Technical Components

• CommandDef: Registry entry in hermes_cli/commands.py that defines slash commands and their metadata.
• process_command(): Function in cli.py that executes the logic for specific CLI/slash commands.
• build_environment_hints(): Located in agent/prompt_builder.py, this function emits factual host and backend guidance (OS, shell, paths) to the system prompt.

Sources: skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md:41-45, skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md:73-75

Advanced CLI Interaction

Multi-Line Input and Shortcuts

The CLI supports advanced terminal interaction patterns:

• Alt+Enter / Ctrl+J: Inserts a newline without sending the message.
• Ctrl+C: Interrupts the agent's current response.
• Ctrl+V: Pastes images from the clipboard for visual analysis.
• Tab: Triggers autocomplete for slash commands starting with /.

Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tips.md:25-48

Context and Global Customization

Users can steer agent behavior without modifying CLI flags by placing markdown files in the working directory:

• AGENTS.md: Provides project-specific instructions and architecture notes.
• SOUL.md: Defines the agent's identity, personality, and tone. This file is loaded from HERMES_HOME/SOUL.md and replaces the default system identity.

Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md:10-18, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:10-15

Hermes CLI commands provide a comprehensive interface for managing the agent's lifecycle, from installation and health checks to complex session management and multi-agent orchestration. By utilizing environment variables like HERMES_HOME and context files like AGENTS.md, developers can precisely control the agent's operational environment and behavior.