hermes_cli — Command-Line Interface

🎯 Why This Module Exists

Without hermes_cli, every tool that wanted to interact with an Hermes agent would need to implement its own argument parsing, authentication handshake, provider discovery, configuration loading, and terminal rendering logic. The CLI module exists to collapse all of those responsibilities into a single, cohesive entry point that speaks the language of the terminal user. It absorbs the complexity of 100+ model providers, multiple authentication strategies (OAuth device-code flows, API-key vaults, rotating credential pools), YAML-based multi-profile configuration, and a curses-driven interactive UI — so that the agent core can remain a pure reasoning engine free from I/O concerns. It also serves as the only place where managed-mode detection occurs, meaning enterprise deployments that inject corporate policies only need to hook into this one module. If hermes_cli were removed, every downstream consumer — scripts, CI runners, IDE extensions — would have to re-derive these capabilities independently, creating a combinatorial explosion of configuration bugs and auth failures.

🚶 Step-by-Step Narrated Walkthrough

Follow a single hermes chat -m gpt-4 command as it flows through the entire hermes_cli pipeline:

1. Shell invocation — The user runs hermes chat -m gpt-4. Python’s __main__ hook calls main.py:main().
2. Profile pre-parse — Before full argument parsing, profiles.py scans sys.argv for --profile to determine which config directory to load. This two-pass design lets profile selection happen before any config-dependent defaults are resolved.
3. Argparse dispatch — main.py builds the full ArgumentParser with 150+ sub-commands registered from commands.py:CommandDef instances. The chat sub-command is matched and its handler cmd_chat() is selected.
4. Config loading — config.py reads ~/.hermes/config.yaml (or the profile-specific path), merges environment overrides, and performs managed-mode detection by checking for a .hermes-managed sentinel file. Managed mode restricts which providers and settings are available.
5. Auth resolution — auth.py determines the authentication strategy for the requested provider. For OpenAI, it checks (in order): environment variable OPENAI_API_KEY, credential pool file with file-locking, stored OAuth token, and finally falls back to an interactive OAuth device-code flow that prints a URL and waits for the user to authorize.
6. Provider resolution — providers.py looks up the provider metadata for gpt-4, while runtime_provider.py applies the runtime priority chain: explicit -m flag > profile default > config default > environment variable > built-in fallback.
7. Model normalization — model_normalize.py canonicalizes gpt-4 into its full API identifier (e.g., gpt-4-0613), resolving aliases and version shortcuts. model_switch.py prepares the hot-swap machinery so the user can change models mid-session with /model.
8. Agent initialization — The CLI constructs the agent core with the resolved provider, model, and credential, then attaches callbacks.py event handlers for streaming token display, tool-call rendering, and error surfacing.
9. Interactive loop — curses_ui.py (with graceful fallback to plain input() on dumb terminals) presents the prompt. The skin_engine.py applies the active theme’s color palette to all output elements.
10. Slash-command dispatch — If the user types /skills, the input is intercepted by the command registry before reaching the agent. skills_hub.py queries the Skills Hub API, presents results via curses_ui.py multi-select, and installs chosen skills.
11. Session teardown — On /exit or Ctrl-C, the CLI gracefully shuts down the agent, flushes any pending gateway connections (gateway.py), and writes session history to disk.

Provider Resolution Priority Chain

The Problem: When the user requests a model like gpt-4, multiple configuration sources may specify different providers and credentials. The CLI must deterministically resolve which provider endpoint and API key to use, respecting explicit overrides while providing sensible defaults.

The Approach: The resolution follows a strict priority chain evaluated top-to-bottom. At each level, if a value is found, it is used and lower levels are skipped. The chain is: (1) explicit CLI flag (-m/--provider), (2) active profile’s default, (3) global config default, (4) environment variable (HERMES_PROVIDER), (5) built-in fallback. Each level can specify both the provider and the model independently, so a user can override the model while inheriting the profile’s provider.

Why This Algorithm: A simple “last-write-wins” merge would create unpredictable behavior when environment variables and config files interact. The explicit priority chain makes the outcome deterministic and debuggable — users can run hermes doctor to see exactly which level each setting was resolved from. The time complexity is O(1) per setting (constant number of levels), so it adds zero overhead to startup.

graph TD
    INPUT["Model request\n'gpt-4'"] --> CLI_FLAG{"-m flag\nprovided?"}
    CLI_FLAG -->|Yes| USE_FLAG["Use CLI flag\nprovider + model"]
    CLI_FLAG -->|No| PROFILE{Profile\ndefault set?}
    PROFILE -->|Yes| USE_PROFILE["Use profile\ndefault"]
    PROFILE -->|No| CONFIG{Global config\ndefault set?}
    CONFIG -->|Yes| USE_CONFIG["Use config\ndefault"]
    CONFIG -->|No| ENV{ENV var\nHERMES_PROVIDER?}
    ENV -->|Yes| USE_ENV["Use env var"]
    ENV -->|No| FALLBACK["Built-in\nfallback provider"]
    USE_FLAG --> NORMALIZE["model_normalize.py\nCanonicalize name"]
    USE_PROFILE --> NORMALIZE
    USE_CONFIG --> NORMALIZE
    USE_ENV --> NORMALIZE
    FALLBACK --> NORMALIZE
    NORMALIZE --> RESOLVE["runtime_provider.py\nBuild API client"]

Hot Paths

The most performance-sensitive code paths in this module:

• Startup to first prompt: Profile pre-parse + config load + auth check — target <500ms. The two-pass argv scan is O(n) on argument count (negligible). Config loading is I/O-bound on a single YAML file (~1ms). Auth is the bottleneck only when an OAuth flow is triggered (user-interactive, not counted).
• Command dispatch: Slash-command lookup in the CommandDef registry — O(n) linear scan over ~150 entries with short-circuit on prefix match. At 150 entries this is sub-microsecond; a hash map would save nothing and lose fuzzy-match capability.
• Streaming token rendering: callbacks.py receives tokens one at a time and writes to stdout. The skin engine applies ANSI codes per-token — O(1) per token. Buffering is left to the terminal emulator.

Resource Usage

• Memory: The command registry, provider metadata, and model catalog are loaded once at startup (~2MB). Conversation history is held in memory for the session duration; long sessions with tool calls can grow to tens of MB. No explicit caching layer — the agent core owns response caching.
• I/O: Config files are read once at startup and written only on explicit save. The credential pool file is opened with flock() for each auth check (~1 read per command). Gateway health checks are periodic (every 30s) and use a single HTTP GET.
• Network: Provider API calls are pass-through to the agent core. The CLI itself makes network calls only for OAuth flows (token endpoint polling) and Skills Hub queries (on-demand).