fix(cli): hermes-agent --help/--version print help instead of running a model turn (#54648, salvage #54649)

[teknium1]

hermes-agent --help, -h, --version and a bare hermes-agent now print help/version and exit instead of running a real model turn, and hermes-agent --query … actually runs the query you passed (#54648, salvage of #54649).

Changes

• hermes-agent console script → agent.legacy_cli:main, an argparse layer over the unchanged run_agent.main() (salvaged from @ooiuuii's fix(cli): guard legacy hermes-agent entrypoint #54649, authorship kept).
• python run_agent.py routes through the same parser instead of fire. That is also what the installer's PATH launcher ~/.local/bin/hermes-agent runs, so the launcher is fixed too.
• The argument layer sits in a topical sibling (agent/legacy_cli.py) and does not grow the run_agent.py facade. The runner is injected (run=), so python run_agent.py does not import itself twice.
• Docs: added a hermes-agent section to the CLI commands reference.

Validation

Live repro: before: on origin/main, the real pip-style hermes-agent wrapper plus the installer launcher were run against a loopback fake provider. --help, -h, --version and no args each made 1 model call with the hard-coded "Python 3.13" demo query. --query "say hi" also sent the demo query. The launcher's --version ran a turn and then exited 2. After: the same probe gives 0 model calls for every metadata/bare case, all rc=0, and they print usage: hermes-agent … / Hermes Agent v0.21.4 (2026.9.21). --query "say hi" makes 1 call carrying say hi.

invocation	origin/main	this PR
hermes-agent --help / -h	1 model call (demo query)	help, 0 calls
hermes-agent --version	1 model call	version, 0 calls
hermes-agent (no args)	1 model call	help + hint, 0 calls
launcher --version	1 model call, rc=2	version, 0 calls
hermes-agent --query "say hi"	sends the demo query	sends say hi

Tests: 2 invariants in tests/agent/test_legacy_cli.py. Each resolves the hermes-agent target from pyproject [project.scripts] and calls it the way pip's wrapper does (no args, argv in sys.argv). On origin/main all 5 cases (4 parametrized + 1) fail. With the fix they pass. tests/agent/ + tests/scripts/install/ were run via scripts/run_tests.sh. ruff, the tmp-literal check, the windows-footgun check, compat pointers and git diff --check are all clean.

Root cause: a console script calls its target with no arguments, and hermes-agent pointed straight at run_agent.main, whose query=None default is a built-in demo prompt. fire only parsed argv under __main__, so no flag was ever read.

Notes

• Existing tests: the salvaged PR's 5 tests (including a pyproject-string change-detector) were replaced by the 2 invariants above. No existing test on main asserted the buggy behaviour.
• The core E2E wave-2 PR (test: E2E suites for profile isolation, key routing, terminal transcripts, hermes update and live providers (core E2E wave 2) #120326) pins this bug as a strict xfail (hermes-agent-help in tests/e2e/core/upgrade/test_fresh_process_entrypoints.py). Whichever of the two PRs lands second must drop that _XFAIL entry, or the strict xfail will XPASS-fail.
• Not in scope: the installer's --no-venv launcher branch writes exec hermes run_agent.py "$@". That prints "'run_agent.py' is not a hermes command" for every invocation. It never starts a turn, so it is a different defect, left for a follow-up.
• Credit: @ooiuuii (fix(cli): guard legacy hermes-agent entrypoint #54649, salvaged here) and @AlexFucuson9 (fix(agent): intercept --version/--help in run_agent.main() #54682, the same --version/--help intercept inside run_agent.main(); superseded).

Fixes #54648

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 11fdefd — fix(cli): move the hermes-agent argv layer into agent/legacy}

⚠️ Warnings

CI timings · View report · View job

Wall time 8m40s vs 6m10s (+40.5%). 11 job(s) slower, 2 faster, 1 unchanged.

• Python lints / Windows footguns (blocking): +100.0s
• Python tests / Run tests: +81.0s
• Docs Site / docs-site-checks: +50.0s
• Check uv.lock / uv lock --check: +30.0s
• Check no committed infographics / check-no-committed-infographics: +27.0s