hermes auth Command — Complete Reference & Examples

Overview

hermes auth manages pooled credentials for LLM and service providers. Multiple credentials can be stored per provider so Hermes can rotate keys when a provider is rate-limited or exhausted.

hermes auth <subcommand>

Subcommands

add <provider>

Add a pooled credential.

hermes auth add openrouter
hermes auth add openrouter --api-key $OPENROUTER_API_KEY
hermes auth add anthropic --type oauth
hermes auth add nous --type oauth --label team-key

Flags:

• --type {oauth,api-key} — Credential type.
• --label LABEL — Optional display label.
• --api-key API_KEY — API key value (otherwise prompted securely).
• --portal-url, --inference-url — Nous portal/inference base URLs.
• --client-id CLIENT_ID — OAuth client id.
• --scope SCOPE — OAuth scope override.
• --no-browser — Do not auto-open a browser for OAuth login.
• --timeout TIMEOUT — OAuth/network timeout in seconds.
• --insecure — Disable TLS verification for OAuth login.
• --ca-bundle CA_BUNDLE — Custom CA bundle for OAuth login.

list [provider]

List pooled credentials.

hermes auth list
hermes auth list openrouter

remove <provider> <target>

Remove a credential by index, entry id, or exact label.

hermes auth remove openrouter 1

reset <provider>

Clear exhaustion status for all credentials of a provider.

hermes auth reset openrouter

status <provider>

Show auth status for a provider.

hermes auth status anthropic

logout <provider>

Log out a provider and clear stored auth state.

hermes auth logout anthropic

spotify [login|status|logout]

Authenticate Hermes with Spotify via PKCE.

hermes auth spotify login
hermes auth spotify status
hermes auth spotify logout

Flags:

• --client-id CLIENT_ID — Spotify app client id (or HERMES_SPOTIFY_CLIENT_ID).
• --redirect-uri REDIRECT_URI — Allow-listed localhost redirect URI.
• --scope SCOPE — Override requested Spotify scopes.
• --no-browser — Do not open the browser automatically.
• --timeout TIMEOUT — Callback/token exchange timeout in seconds.

Examples

# Add an API key from an environment variable
hermes auth add openrouter --api-key $OPENROUTER_API_KEY

# Add several keys for rotation
hermes auth add openrouter --api-key $KEY1 --label key-1
hermes auth add openrouter --api-key $KEY2 --label key-2
hermes auth add openrouter --api-key $KEY3 --label key-3

# Add an OAuth provider
hermes auth add anthropic --type oauth

# Check and reset a provider after rate limits
hermes auth status openrouter
hermes auth reset openrouter

# List and remove a credential
hermes auth list openrouter
hermes auth remove openrouter 1

Tips

• Add 3–5 keys for high-throughput providers so Hermes can rotate when one key hits a rate limit.
• --api-key reads from the environment securely; if omitted, the CLI prompts without echo.
• hermes auth reset clears exhaustion/cooldown state but does not delete credentials.
• Spotify uses PKCE; set HERMES_SPOTIFY_CLIENT_ID to avoid passing --client-id every time.