Mercury CLI
Documentation

Providers

Providers and sign-in

Mercury routes a session's model to the provider that owns its identifier. Each provider owns its own wire, credentials and refusals, and nothing falls through from one provider to another.

Provider access

  • OpenAI: A ChatGPT subscription sign-in or an API key.
  • Anthropic: A subscription account, or usage-based billing through an Anthropic Console sign-in or an API key.
  • OpenRouter: One credential for the whole catalogue, by OAuth or an API key.
  • Google: An API key or Google OAuth.
  • Hugging Face: A device-code sign-in or a Hub token.
  • Moonshot: A device-code sign-in or an API key.
  • Z.AI: An API key.
  • DeepSeek: An API key.
  • Local servers: No sign-in. A discovered server, such as Ollama, LM Studio, vLLM or llama.cpp, is served at each model's own base URL.
  • Custom endpoint: No sign-in. A configured OpenAI-compatible endpoint.

The readiness detail of the Hugging Face and local providers carries a caveat until they are verified against a live endpoint.

Sign in to a provider

To sign in to a provider, follow these steps:

  1. Enter /logins.
  2. Select the provider's entry in the sign-in catalogue.
  3. Complete the sign-in or the key entry.

Mercury records when the credential landed in the sign-in ledger and can start sessions on that provider's usable models.

/logins opens the same card the first run shows. From the command line, mercury auth login|status|logout|token signs in, shows the status, signs out or mints a long-lived token.

Inspect provider accounts

To inspect provider accounts, follow these steps:

  1. Enter /accounts.

The board shows one slot per signed-in identity across every provider, derived from each provider's own account resolvers. Each provider's header carries the provider's name alone, and the rows beneath it name each sign-in with its kind and identity. A provider with no ceiling shows how many sign-ins it holds beside its name.

Slots carry presence facts and masked key tails only, never a secret value. An environment-pinned key is shown with its precedence honored and is refused for editing, and it is never a Mercury-held sign-in. Removal of a slot is routed to the store that owns it.

A ceiling caps concurrent Mercury-held sign-ins:

  • Anthropic: Two.
  • OpenAI: Two.

Every sign-in path consults one typed refusal before adding a concurrent sign-in, so a sign-in that would exceed the ceiling is refused before it is added.

Session defaults

The default provider is the provider of the most recent sign-in. A fresh, unpinned session starts on that provider's newest model the credential can use. A gated row is never chosen, and a provider with no usable row falls through to the next most recent sign-in.

  • /model: Says which model was picked and why.
  • /defaultprovider: Makes a provider the most recent sign-in by your choice, as an entry in the same ledger.
  • MERCURY_MODEL: Pins a model ahead of the computed default.

With no sign-in anywhere there is no default: the Boot face and /model say so and point at /logins.

Credential changes and refusals

A sign-in or a removal tells every runner the daemon hosts to read the account again. A usage-limit verdict is trusted only for the account that observed it and reads as unknown once the signed-in account is another. The verdict lapses at the reset the reply named, or after a bounded span when it named none. An expired sign-in is reported as an expired sign-in, never as a used-up usage window, and the notice names the sign-in command, /logins anthropic for the Anthropic provider.

On the Anthropic wire, an authentication refusal never enters the retry backoff. Mercury attempts credential recovery once when the active sign-in or key helper can refresh the credential. A changed credential gets one immediate retry. A failed refresh, an unchanged credential or another authentication refusal ends the request. The blocker names the account when known and the sign-in command, or the environment variable or helper that supplied the rejected credential.

A provider whose credential does not resolve refuses with text that names where to sign in or store a key, never a generic error. An undiscovered local model refuses with the probe route rather than guessing a port. A routed request never falls through to another provider, and a reached usage window also caps delegation: a subagent is not dispatched to another provider instead.

Models and effort, Web search, Quickstart, Saturn scheduling