Hermes Agent CLI Beginner's Guide: From Installation to Your First AI Agent Task

Learning Objectives

By the end of this tutorial, you will be able to:

• Install Hermes Agent on your operating system
• Set up a provider and start your first conversation
• Use Hermes Agent for interactive chat and single-query tasks
• Navigate Hermes Agent' key commands and features
• Troubleshoot common installation issues

Time needed: 10–15 minutes

Difficulty: Beginner

Which version is covered? This tutorial covers the Hermes Agent CLI — the command-line version you run in your terminal. The recommended installer also installs the Hermes Agent Desktop app automatically. If you want the desktop app only, download it from the official website.

Prerequisites

Before you begin, make sure you have:

What is Hermes Agent?

Hermes Agent is an open-source AI agent by Nous Research that runs in your terminal, desktop app, and messaging platforms. Unlike coding copilots, Hermes Agent is a general-purpose autonomous agent with persistent memory, self-improving skills, and multi-platform gateway support. It works with 300+ models from any provider.

What is Nous Portal? Nous Portal is a subscription service from Nous Research that gives you access to 300+ models plus tool gateway tools (web search, image generation, TTS, cloud browser) with a single OAuth login. It is the fastest way to get started with Hermes Agent — no API keys to manage.

What is a terminal? A terminal (also called command line) is a window where you type commands instead of clicking buttons. On Windows it is called PowerShell; on macOS it is called Terminal.

How to Open Your Terminal (Step by Step)

If you are not sure how to open a terminal, follow the steps for your system below.

Download & Install

Option A: Hermes Agent Desktop Installer (Recommended)

The desktop installer installs both the CLI and the desktop app at once. Simply download the installer from the official Hermes Agent website and run it:

• Windows: download Download for Windows, open the installer, and follow the on-screen instructions.
• macOS: download Download for macOS, open the .dmg file, and drag Hermes Agent to your Applications folder.
• Linux: the desktop installer is not yet available — use Option B below.

After installing, verify the CLI works by running hermes --version in your terminal.

Option B: CLI Only (All Platforms)

For a command-line only install, use the shell installer. It handles all dependencies automatically — Python, Node.js, ripgrep, ffmpeg — you only need Git.

irm https://hermes-agent.nousresearch.com/install.ps1 | iex

hermes --version

Set Up a Provider

Fastest Path: Nous Portal

One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

hermes setup --portal

This logs you in, sets Nous as your provider, and turns on the Tool Gateway in a single command.

Other Providers

If you already have an API key from another provider (OpenAI, Anthropic, OpenRouter, etc.), use the setup wizard:

hermes setup

Or set the provider interactively:

hermes model

The setup wizard offers three modes:

• Quick Setup (Nous Portal) — free OAuth login, no API keys. The recommended fast path.
• Full Setup — walk through every provider, tool, and option yourself.
• Blank Slate — everything starts off except the minimum needed to run an agent. Choose this when you want full control over what is enabled.

Good Defaults for Common Providers

Your First Chat

Step 1: Start an interactive session

hermes

You will see the Hermes Agent prompt, ready for you to type a message. If this is your first time, it may take a moment to set up the session.

Step 2: Say hello

Type a message and press Enter:

Hello! What can you do?

Hermes Agent will respond with a summary of its capabilities. Try a few more:

• What is the current date and time? — Hermes Agent checks the system time
• List the files in this directory — Hermes Agent uses the file system tool
• Search the web for the latest news about AI agents — Hermes Agent uses the web search tool (if enabled)

Step 3: Ask a single question without interactive mode

hermes chat -q "What is the capital of France?"

This runs a single query and exits — useful for scripts and automation.

Step 4: Exit Hermes Agent

In an interactive session, type /exit and press Enter, or press Ctrl + C.

Useful Commands

Troubleshooting

How to Update

hermes update

Frequently Asked Questions

Do I need a paid plan?

Hermes Agent itself is free and open-source (MIT license). You need either a Nous Portal subscription, an API key from a provider (OpenAI, Anthropic, etc.), or a local model (Ollama) to power the agent. The fastest free path is Nous Portal's free tier.

Can Hermes Agent work without internet?

Yes, if you use a local model through Ollama. However, certain features (web search, image generation, TTS) require internet access.

What models can Hermes Agent use?

Hermes Agent works with 300+ models through Nous Portal, plus any model accessible through OpenAI, Anthropic, OpenRouter, Google, DeepSeek, xAI, or local models via Ollama.

Can Hermes Agent browse the web?

Yes, if the web search tool is enabled (it is on by default when using Nous Portal or with your own API key configured).

Is my data private?

Hermes Agent is open-source and runs locally on your machine. Your conversations and data are processed by the LLM provider you choose. Review the data usage policy of your provider for details.

What's Next

• Explore the desktop app: Run hermes desktop to launch the graphical interface.
• Connect messaging platforms: Set up Telegram, Discord, Slack, or other platforms with hermes gateway setup.
• Create skills: Hermes Agent can create reusable skills from your conversations — just ask it to save a procedure as a skill.
• Use MCP servers: Connect external tools through the Model Context Protocol.
• Read the full documentation: Visit hermes-agent.nousresearch.com/docs for the complete guide.