Fixes
Fix: "hermes: command not found" after a successful install
You ran the installer, it printed a success message, and then:
zsh: command not found: hermesNothing is broken. Hermes installs into ~/.hermes/hermes-agent/ and symlinks its
launcher into ~/.local/bin/hermes — a directory that plenty of systems do not put
on PATH by default. Your shell simply cannot see a binary that is sitting right
there on disk.
Step 1 — confirm the install actually succeeded
Before touching anything, check whether the binary exists:
ls -l ~/.local/bin/hermesIf that prints a symlink pointing into ~/.hermes/, the install is fine and this is
a PATH problem — skip to step 2.
If it prints No such file or directory, the install genuinely did not complete. Look
for an install log, re-run the installer, and read the output rather than assuming it
worked. A common cause here is the installer failing partway through on a missing
system dependency (uv, Python 3.11, Node.js, ripgrep, or ffmpeg) and reporting
that failure in a line you scrolled past.
Step 2 — check whether the directory is on PATH
echo $PATH | tr ':' '\n' | grep -x "$HOME/.local/bin"Output means it is on your PATH and something stranger is going on — jump to
the shell-cache section below. No output confirms the diagnosis.
Step 3 — add it to the right profile file
Which file you edit depends on your shell. Find out what you are actually running:
echo $SHELL| Shell | File to edit |
|---|---|
| zsh (macOS default) | ~/.zshrc |
| bash (most Linux) | ~/.bashrc |
| bash (login shells on macOS) | ~/.bash_profile |
| fish | ~/.config/fish/config.fish |
For zsh or bash, append the line:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcFor fish, the syntax is different:
fish_add_path ~/.local/binStep 4 — reload and verify
Open a new terminal, or reload in place:
exec $SHELL -l
hermes --versionThen confirm the install itself is healthy rather than just reachable:
hermes doctorhermes doctor checks dependencies, config location, and provider setup in one
pass. Run it before you debug anything else — it turns most “Hermes is broken”
reports into a one-line answer.
If PATH looks correct but the error persists
Two things cause this.
A stale command hash. Both bash and zsh cache the location of executables. If you had a failed install earlier in the same session, the shell may still be holding the old, wrong answer:
hash -rA conflicting binary earlier in PATH. Check what your shell actually resolves:
which -a hermesMore than one result means something else named hermes is shadowing the real
one. Reorder your PATH so ~/.local/bin comes first, which is what the export
line above already does — but only if it runs after whatever adds the conflicting
directory.
The systemd case
If Hermes works in your terminal but the service unit fails with the same error, this is expected. systemd does not read your shell profile. Use an absolute path:
[Service]
ExecStart=/home/YOUR_USER/.local/bin/hermes gateway
Environment="PATH=/home/YOUR_USER/.local/bin:/usr/local/bin:/usr/bin:/bin"Reload and restart after editing:
systemctl --user daemon-reload
systemctl --user restart hermesWhat not to do
Do not sudo the installer to “fix permissions.” It installs Hermes into root’s home
directory instead of yours, and you end up with an agent that cannot read your config
and a second copy of the problem. If you already did this, remove the root-owned
install before reinstalling as your normal user.
FAQ
Do I need to reinstall Hermes to fix this?
No. A "command not found" error after the installer reports success means the files are on disk but your shell cannot see them. Reinstalling puts the same files in the same place and changes nothing. Fix PATH instead.
Why does it work in one terminal but not another?
The installer usually appends the PATH line to a single shell profile. If you launch a different shell — zsh in one window, bash in another, or a non-login shell from an IDE — that profile is never read. Add the export line to every profile you actually use.
Does this affect the systemd service too?
Yes, and more often. systemd units start with a minimal environment that does not include your login shell's PATH. Always use the absolute path in ExecStart.