Agent CLI (HermesCLI)

HermesCLI is a small command-line tool that ships alongside the Hermes agent and runs locally on the managed host. When you're standing at (or remoted into) a machine that won't check in, it answers the questions that matter first: is the agent registered, when did it last heartbeat, is its certificate still valid, and can it reach the server? It also lets you fix the common causes on the spot — repoint the server URL, adjust log level, and start or restart the service — without hand-editing JSON.

Running the CLI#

The tool is invoked as HermesCLI. Run it from an elevated (Administrator) prompt when you need to touch the service or configuration — status and read-only commands work without elevation. Every command follows the same shape:

HermesCLI <group> <command> [options]

The command groups are:

Add --help after any group to list its commands, and --version to print the CLI version. Most read commands also accept --json for machine-readable output you can pipe into a script or a monitoring check.

Quick status#

HermesCLI status is the fastest way to see where a host stands. It prints one row per configured server with a colour-coded Status, the certificate expiry date, and the last heartbeat (with a "how long ago" hint), followed by the hostname and the service state.

HermesCLI status
HermesCLI status --json

The Status column is derived locally from the agent's state and certificate:

Detailed info#

The info group drills into specifics. Each command supports --json.

Debugging & logs#

Test connectivity#

HermesCLI debug connection opens a TCP connection to the host and port taken from each enabled server's URL and reports success/failure with latency. This isolates whether the problem is network reachability (firewall, routing, DNS) rather than the agent itself.

# Test all configured (enabled) servers
HermesCLI debug connection

# Test one configured server by name
HermesCLI debug connection --name production

# Test an arbitrary URL, e.g. before adding it
HermesCLI debug connection --url https://athena.example.com:8444 --json

View and tail logs#

HermesCLI debug logs reads the most recent agent log file and colour-codes each line by level. It's the quickest way to see why an agent is failing without hunting for the file.

# Last 50 lines (default)
HermesCLI debug logs

# Last 200 lines
HermesCLI debug logs --lines 200

# Only errors, or warnings-and-above
HermesCLI debug logs --errors
HermesCLI debug logs --warnings

# Only lines containing some text
HermesCLI debug logs --filter "certificate"

# Follow new log output live (Ctrl+C to stop)
HermesCLI debug logs --follow

# Open the current log file in an editor (Windows)
HermesCLI debug logs --open

List file paths#

HermesCLI debug paths prints every location the agent uses — the configuration file, the data directory, agent state, certificate and CA files, the logs directory, the install directory, and each per-server sub-directory — and whether each one currently exists. Handy when you need to know exactly where to look or what to back up.

The data directory follows the Agent:DataPath setting; when that is left empty it defaults to %ProgramData%\Hermes. HermesCLI locates appsettings.json by checking the current directory, then Program Files\Hermes, then Program Files (x86)\Hermes.

Configuration#

The config group reads and writes the agent's appsettings.json safely — it validates values and preserves the rest of the file — so you don't have to edit JSON by hand.

# Show current settings, servers, and logging
HermesCLI config show

# Create a fresh appsettings.json with defaults (use --force to overwrite)
HermesCLI config init

# Change a single setting
HermesCLI config set HeartbeatIntervalSeconds 30

# Reset settings to defaults (server list is preserved)
HermesCLI config reset

The settings you can change with config set:

Managing server connections#

An agent can connect to more than one server (it's multi-homed via the Agent:Servers[] list). The config server commands manage that list. Each entry has a unique Name, a URL, an optional registration token, and an enabled flag. Names must be a valid folder name (no path separators, not . or .., 50 characters or fewer), because they become the per-server identity directory on disk.

# List configured servers (and whether each has registered)
HermesCLI config server list

# Add a server connection
HermesCLI config server add --name production --url https://athena.example.com:8444 --token <registration-token>

# Temporarily disable / re-enable a server without removing it
HermesCLI config server disable production
HermesCLI config server enable production

# Remove a server entry (its data directory is left in place)
HermesCLI config server remove production

For how tokens are created and scoped on the server side, see Registration Tokens; for the full enrolment flow, see Agent Enrollment.

Log level#

When you need more detail in the log file, raise the log level, reproduce the issue, then turn it back down. Valid levels are Verbose, Debug, Information, Warning, Error, and Fatal.

# Show current logging configuration
HermesCLI config logging show

# Set the default level
HermesCLI config logging set Debug

# Turn up (or down) one component only, then remove the override later
HermesCLI config logging override Hermes.Agent Debug
HermesCLI config logging remove Microsoft

Remember to service restart for a level change to apply. For the server's own logging, see Server Logging & Log Retention.

Service control (Windows)#

On Windows the agent runs as the HermesAgent service. The service commands wrap the common operations and require Administrator privileges. (Service management is Windows-only; on Linux the agent runs under systemd.)

HermesCLI service status
HermesCLI service start
HermesCLI service stop
HermesCLI service restart

status reports whether the service exists, its run state, start type, and process ID. start, stop, and restart wait up to 30 seconds (override with --timeout <seconds>) for the state change to complete. All of these accept --name if you run the service under a non-default name.

Shell completion & interactive mode#

Generate tab-completion for your shell, or drive the whole tool from a menu when you'd rather not remember command names:

# Print a completion script (powershell, bash, or zsh)
HermesCLI completion powershell
HermesCLI completion powershell --install   # show install instructions

# Menu-driven mode (alias: i)
HermesCLI interactive

A typical troubleshooting pass#

When a host shows as offline in the console, these steps localise the problem quickly:

1. HermesCLI status — is the service running and how old is the last heartbeat?
2. HermesCLI service status — if the service is stopped, service start.
3. HermesCLI debug connection — can the host reach the server host/port at all?
4. HermesCLI info cert — is the certificate expired or about to expire?
5. HermesCLI debug logs --errors — what is the agent actually complaining about?
6. Fix the cause (repoint with config server, adjust a config set value), then HermesCLI service restart.