Hermes Auth CLI Parity Manifest

Read-only audit of the operator-visible CLI surface for provider auth and provider lifecycle in canonical Python Hermes (workspace-mineru/hermes-agent/). Captured for downstream Gormes planner splits - no Hermes or Gormes runtime code changed by this pass.

Scope: only commands that authenticate, configure, or remove an inference provider (or the Spotify control-plane provider). Out of scope: chat, gateway, cron, sessions, tools, mcp non-login subcommands, slack manifest, whatsapp, backup, status, doctor.

All paths below are absolute Python Hermes paths.

1. Command-tree manifest (non-deprecated surface)

hermes auth is the canonical pooled-credential CLI; hermes model, hermes setup, and hermes mcp login are the supported adjacent surfaces a user reaches when picking a provider, running the full wizard, or repairing a broken MCP OAuth session.

Notes:

• hermes auth and hermes model together are the operator-visible auth surface. hermes setup model reaches the same select_provider_and_model path as hermes model, but routes through the wizard’s defaults/quick logic.
• hermes logout (top-level, not hermes auth logout) still exists and is not in the deprecation note below - it is supported but narrowly scoped (--provider choices: nous, openai-codex, spotify). It dispatches to the same logout_command as hermes auth logout. Parser at hermes_cli/main.py:8232-8243.
  • This is an open question for parity: see section 5.

2. Deprecation note - hermes login

hermes login is the historical entry point that the Gormes README must not recommend. The parser is still registered (so hermes login --help still prints), but the handler is a stub that prints a deprecation message and exits cleanly.

Source: hermes_cli/auth.py:3848-3853

def login_command(args) -> None:
    """Deprecated: use 'hermes model' or 'hermes setup' instead."""
    print("The 'hermes login' command has been removed.")
    print("Use 'hermes auth' to manage credentials,")
    print("'hermes model' to select a provider, or 'hermes setup' for full setup.")
    raise SystemExit(0)

Parser definition (still wired so flags do not break old scripts, but every flag is ignored): hermes_cli/main.py:8186-8227. Flags accepted but no-op: --provider {nous,openai-codex}, --portal-url, --inference-url, --client-id, --scope, --no-browser, --timeout, --ca-bundle, --insecure.

Redirect targets:

• hermes auth - pooled credentials.
• hermes model - provider + model picker (and the OAuth flow for that provider).
• hermes setup - full or sectioned wizard.

Gormes parity rule. Gormes follows the Q1B decision: do not register a top-level login subcommand. gormes login should travel through Cobra’s unknown-command path and emit deterministic unknown_command_login_suggested_auth_add guidance: did you mean "gormes auth add <provider> --type oauth"?. It must not parse legacy login flags, run OAuth, open a browser, or mutate auth state. README and docs should never tell a user to run hermes login --provider openai-codex; the supported recipe is hermes auth add openai-codex (or hermes model then pick OpenAI Codex).

3. Per-provider auth add behavior matrix

<provider> is the positional arg to hermes auth add. _OAUTH_CAPABLE_PROVIDERS = {"anthropic", "nous", "openai-codex", "qwen-oauth", "google-gemini-cli"} (hermes_cli/auth_commands.py:36). For all other providers in PROVIDER_REGISTRY, --type oauth is rejected (raises SystemExit("hermes auth add <provider> is not implemented for auth type oauth yet.") via the catch-all at auth_commands.py:336); only --type api-key works.

4. auth list / status / logout / reset / spotify behavior

auth list [provider] - Resolves the filter via _normalize_provider (so aliases like or become openrouter). With no filter, iterates over sorted(PROVIDER_REGISTRY.keys() + {"openrouter"} + list_custom_pool_providers()). For each provider with at least one entry, prints a header <provider> (N credentials): and one line per entry showing index, label, auth_type, source (with the manual: prefix stripped via _display_source), exhaustion status (_format_exhausted_status distinguishes rate-limited / auth-failed / exhausted with retry-window math), and a <- marker on the currently-selected entry. Source: hermes_cli/auth_commands.py:339-363.

auth status <provider> - Required positional. Calls auth.get_auth_status(provider) (auth.py:3419-3446) which dispatches to per- provider status helpers (get_nous_auth_status auth.py:3256+, get_codex_auth_status auth.py:3309+, get_qwen_auth_status auth.py:1425+, get_gemini_oauth_auth_status auth.py:1495+, get_spotify_auth_status auth.py:1938+, get_api_key_provider_status auth.py:3358+, get_external_process_provider_status auth.py:3389+). Prints <provider>: logged in plus indented metadata (auth_type, client_id, redirect_uri, scope, expires_at, api_base_url) or <provider>: logged out (<reason>) on failure. Source: hermes_cli/auth_commands.py:411-428.

auth logout <provider> - Wraps auth.logout_command with a SimpleNamespace. The underlying command (auth.py:4334-4360) validates is_known_auth_provider, picks the target as provider or active or config_provider, calls clear_provider_auth(target) to wipe providers.<target> from auth.json and clears active_provider if it pointed there, resets model.provider in config when it matched, and prints Logged out of <Display Name>. followed by either Hermes will use OpenRouter for inference. (if OPENROUTER_API_KEY) or Run 'hermes model' or configure an API key to use Hermes.. Source: hermes_cli/auth_commands.py:431-432.

auth reset <provider> - Calls pool.reset_statuses() on the named provider’s pool, which clears every entry’s exhaustion / cooldown so all credentials are eligible again on the next inference call. Prints Reset status on <N> <provider> credentials. Source: hermes_cli/auth_commands.py:404-408.

auth spotify [login|status|logout] - Default action is login (no subcommand). login runs PKCE: builds an authorize URL, opens a browser unless --no-browser or remote-session detected, waits for the localhost callback (_spotify_wait_for_callback, default 180s), exchanges code+verifier for tokens, and stores providers.spotify with set_active=False (Spotify is not an inference provider so it must not steal active_provider). If no client_id is supplied or stored, runs _spotify_interactive_setup to walk the user through creating a Spotify developer app. status and logout route to the generic auth_status_command / auth_logout_command with provider="spotify". Source: hermes_cli/auth_commands.py:435-446, hermes_cli/auth.py:2018-2108.

5. Open questions for the planner

1. hermes logout (top-level) status. Parser at main.py:8232-8243 is live, dispatches to the same logout_command as hermes auth logout, but only exposes provider choices nous|openai-codex|spotify. Is this command on a deprecation path (sibling of hermes login) or supported in parallel? The user’s framing of the parity rule lists hermes auth ... logout as the non-deprecated shape; the planner should decide whether Gormes ships gormes logout, only gormes auth logout, or both.

2. auth_command vs interactive bare hermes auth. The bare invocation prints both pool state and an AWS Bedrock STS identity (auth_commands.py:457-476) that depends on optional boto3. Gormes parity needs a Go path that prints the same pool table; the AWS STS print can be a separate row gated on AWS SDK availability - confirm whether the planner wants AWS bedrock identity in the Goncho equivalent or carved off.

3. auth add bedrock. Source has no explicit handler. The catch-all at auth_commands.py:336 rejects OAuth, and there is no bedrock-specific API-key path because auth_type="aws_sdk". Confirm whether Gormes should match the gap (refuse and tell the user to set AWS env / profile) or close it (offer gormes auth add bedrock --profile <name>).

4. auth add openrouter accepts only --type api-key. Same catch-all at auth_commands.py:336 as bedrock, but openrouter is silently allowed because _normalize_provider rewrites it and the API-key branch at auth_commands.py:194-219 does not require provider in PROVIDER_REGISTRY (the gate at auth_commands.py:163-164 explicitly allows openrouter and custom:*). Confirm Gormes treats openrouter as a first-class provider ID even though it has no ProviderConfig.

5. Vendor-CLI race envelope (Codex CLI / VS Code). The pooled auth add openai-codex path always runs a fresh device-code flow and stores tokens in ~/.hermes/auth.json, rejecting reuse of ~/.codex/. Only the legacy _login_openai_codex flow (still reachable via hermes model -> OpenAI Codex provider when no Hermes credentials exist) prompts to import ~/.codex/auth.json. Gormes parity must replicate the isolation contract - but the planner needs to decide whether gormes auth add openai-codex keeps offering import (parity with cmd_model) or stays strict (parity with auth add). This is the surface the user flagged as the README error.

6. OAuth-capable provider set. _OAUTH_CAPABLE_PROVIDERS = {"anthropic", "nous", "openai-codex", "qwen-oauth", "google-gemini-cli"} is hard-coded in two places (auth_commands.py:36 and again inline at auth_commands.py:173). If a future provider grows OAuth, both spots need updating. The Gormes equivalent should derive this from ProviderConfig.auth_type instead.

7. Spotify out of PROVIDER_REGISTRY. Spotify is reachable only via auth spotify, never via auth add. Parity question: is Spotify a first-class auth provider in Gormes (separate command tree), or should it ride the same auth subparser?

8. hermes mcp login requires auth == "oauth". Header-auth and stdio MCP servers cannot be re-authed via this command; the handler tells the user to hermes mcp remove + hermes mcp add instead (mcp_config.py:613-614). Confirm whether the Gormes equivalent narrows the surface the same way.

9. Top-level hermes login parser still registered. The deprecated subparser still consumes flags so hermes login --provider openai-codex exits cleanly with the deprecation message instead of argparse complaining about unknown args. Gormes parity needs to decide: keep the parser shim (cleanest deprecation), or drop the command entirely and let gormes login produce a “command not found” hint that points to gormes auth.