revka models, providers & auth

This page covers three related parts of the revka CLI: the revka models group for refreshing and inspecting per-provider model catalogs, the revka providers command for listing every supported back-end, and the revka auth group for managing OAuth and subscription authentication profiles (the credentials behind providers like OpenAI Codex, Gemini, and Anthropic subscription tokens).

Reach for these commands when you want to discover which models a provider currently offers, change your default model, confirm an API key works, or log in to a subscription provider that authenticates with OAuth instead of a plain API key.

For the conceptual side of providers — the full catalog, region routing, reliability, and custom endpoints — see Custom providers & local LLMs and the Provider catalog. For configuring credentials in config.toml, see Config: provider, agent & routing.

revka models

Provider model catalogs are fetched live from each provider’s models endpoint and cached on disk. The cache lives at <workspace>/state/models_cache.json and entries are considered fresh for 12 hours. After that they are reported as stale, but stale entries are never deleted — they remain available as a fallback when a live refresh fails.

revka models refresh

Fetch a provider’s current model catalog and write it to the cache.

revka models refresh                       # refresh the configured default provider
revka models refresh --provider openrouter # refresh a specific provider
revka models refresh --all                 # refresh every live-discovery provider
revka models refresh --force               # ignore the fresh cache and fetch now

Flag	Meaning
--provider <ID>	Refresh a specific provider. Defaults to the configured default_provider.
--all	Refresh every provider that supports live model discovery. Cannot be combined with --provider.
--force	Ignore a fresh cache entry and force a live fetch.

Without --force, a refresh that finds a fresh (under 12 hours old) cache entry prints the cached list instead of hitting the network, and reminds you that revka models refresh --force --provider <ID> fetches the latest immediately.

If the live fetch fails or the provider returns an empty list, Revka falls back to the most recent cached catalog (even if it is stale) and tells you how old it is, so a transient provider outage does not leave you without a model list.

Note

The API key used for the refresh is the one resolved from your config and environment (api_key → provider-specific env var → REVKA_API_KEY / API_KEY). A refresh that returns an auth error usually means the wrong key is configured for that provider.

revka models list

Print the cached model list for a provider. This reads only the cache — it never fetches — so run revka models refresh first if the cache is empty.

revka models list                     # list cached models for the default provider
revka models list --provider anthropic

The currently configured default_model is marked with a *. The output also shows how long ago the cache was written. If no cache exists for the provider, the command tells you which revka models refresh command to run.

revka models set

Write a new default_model into config.toml.

revka models set claude-sonnet-4-20250514

This is a convenience wrapper around editing the default_model key directly. Use a model ID that matches your provider’s format — for example OpenRouter uses provider/model-name (anthropic/claude-sonnet-4-6), while Anthropic uses the bare model ID.

revka models status

Show the active model configuration and cache freshness for the default provider.

revka models status

The output reports the configured provider, model, and temperature, then the cached model count, how long ago the cache was written, and whether it is fresh (under 12 hours) or stale.

Providers that support live discovery

revka models refresh (and --all) only works for providers that expose a queryable model catalog:

openrouter, openai, openai-codex, anthropic, groq, mistral, deepseek, xai,
together-ai, gemini, ollama, llamacpp, sglang, vllm, osaurus, astrai,
avian, venice, fireworks, novita, cohere, moonshot, glm, zai, qwen, nvidia,
opencode-go

Any custom:<URL> endpoint also supports live discovery. Refreshing any other provider returns Provider '<id>' does not support live model discovery yet. For those providers, set the model manually with revka models set.

Tip

To probe model catalogs across all configured providers at once — including auth/connectivity status per provider — use revka doctor models. It is the fastest way to verify that your keys work before deploying.

revka providers

List every supported provider with its canonical ID, display name, aliases, and a marker for the one currently active in your config.

revka providers

The output marks the active provider with (active) and tags providers that run locally (such as Ollama) with [local]. Two synthetic entries are always shown:

• custom:<URL> — point Revka at any OpenAI-compatible endpoint.
• anthropic-custom:<URL> — point Revka at any Anthropic-compatible endpoint.

Use a provider ID (or one of its aliases) as the value of default_provider in config.toml, the -p/--provider flag on revka agent, or the REVKA_PROVIDER environment variable. For the full catalog with base URLs, env vars, and capabilities, see the Provider catalog.

Auth management

Most providers authenticate with a plain API key set in config.toml or an environment variable. A few authenticate through OAuth or subscription tokens instead — there is no static API key to paste. The revka auth commands manage those credentials.

Auth profiles are stored separately from config.toml in ~/.revka/auth-profiles.json (a single encrypted JSON file in the config directory) and are keyed by provider plus a profile name (default: default). Multiple profiles let you keep, for example, a personal and a work subscription side by side and switch between them.

Subscription/OAuth providers include:

Provider	Auth style
openai-codex (alias codex)	OAuth — browser or device-code flow, or import existing Codex credentials
gemini	OAuth login
anthropic	Subscription setup token / paste-token

See OAuth & subscription providers for how each provider uses these credentials at request time, and Secrets, pairing & device auth for credential storage.

revka auth login

Start an OAuth login for a subscription provider.

revka auth login --provider openai-codex
revka auth login --provider openai-codex --device-code
revka auth login --provider openai-codex --import ~/.codex/auth.json
revka auth login --provider gemini --profile work

Flag	Meaning
--provider <ID>	Provider to authenticate (e.g. openai-codex, gemini). Required.
--profile <NAME>	Profile name to store the credentials under. Default: default.
--device-code	Use the OAuth device-code flow instead of the redirect flow. Useful on headless hosts.
--import <PATH>	Import an existing auth.json instead of starting a new login. Currently only openai-codex; defaults to ~/.codex/auth.json. Conflicts with --device-code.

The default (non-device-code) flow opens a browser to authorize, then completes by capturing the redirect. On a machine without a browser, use --device-code, or complete the redirect manually with revka auth paste-redirect.

revka auth paste-redirect

Finish an OAuth login by pasting the redirect URL (or raw authorization code) that the provider returned — used when the browser redirect could not be captured automatically.

revka auth paste-redirect --provider openai-codex --input "<URL_OR_CODE>"

Flag	Meaning
--provider <ID>	Provider being authenticated.
--profile <NAME>	Profile name. Default: default.
--input <URL_OR_CODE>	The full redirect URL or the raw OAuth code. If omitted, you are prompted for it.

revka auth paste-token

Store a subscription or setup token directly — used for Anthropic subscription auth, where you supply a token value rather than running a browser flow.

revka auth paste-token --provider anthropic --token "<VALUE>"
revka auth paste-token --provider anthropic --auth-kind api-key

Flag	Meaning
--provider <ID>	Provider (e.g. anthropic).
--profile <NAME>	Profile name. Default: default.
--token <VALUE>	The token value. If omitted, you are prompted to enter it interactively (so it stays out of your shell history).
--auth-kind <KIND>	Override how the token is sent: authorization or api-key.

Caution

Tokens are sensitive credentials. Prefer the interactive prompt (omit --token) so the value is not recorded in your shell history, and enable secrets encryption during onboarding to protect stored credentials at rest.

revka auth setup-token

Interactive alias of paste-token, intended for the Anthropic subscription setup-token flow.

revka auth setup-token --provider anthropic

It accepts the same --provider and --profile flags and prompts for the token value.

revka auth refresh

Refresh an access token from its stored refresh token. Supported for openai-codex and gemini.

revka auth refresh --provider openai-codex
revka auth refresh --provider openai-codex --profile work
revka auth refresh --provider gemini

Flag	Meaning
--provider <ID>	Provider whose token to refresh.
--profile <NAME_OR_ID>	Profile name or full profile id. Optional.

Long-running deployments refresh tokens automatically in-process; this command is for forcing a refresh manually.

revka auth use

Set the active profile for a provider when you keep more than one.

revka auth use --provider openai-codex --profile work

Flag	Meaning
--provider <ID>	Provider to switch.
--profile <NAME>	Profile name or full profile id to make active.

revka auth logout

Remove a stored auth profile.

revka auth logout --provider openai-codex
revka auth logout --provider openai-codex --profile work

Flag	Meaning
--provider <ID>	Provider to log out of.
--profile <NAME>	Profile to remove. Default: default.

revka auth list

List all stored auth profiles across providers.

revka auth list

revka auth status

Show the active profile per provider and each token’s expiry.

revka auth status

Use this to confirm which subscription credentials are in effect and whether any token is close to expiring.

Related pages

• Custom providers & local LLMs — connect Ollama, llama.cpp, and custom endpoints.
• Provider catalog — full table of provider IDs, base URLs, and capabilities.
• OAuth & subscription providers — how Codex, Gemini, Claude Code, and others authenticate.
• Config: provider, agent & routing — the config.toml keys behind these commands.
• revka doctor, status & self-test — probe model catalogs and validate keys with revka doctor models.
• revka agent — override provider and model per session.