Authentication

Sign in to the revenexx CLI with a token, understand how credentials resolve from flags, environment, and config files, and select the tenant your commands apply to.

The CLI authenticates two ways: an interactive browser sign-in for working at a terminal, and a gateway API key for CI and automation. Both end the same way — a validated session saved to disk so later commands don't have to sign in again.

Sign in

Run login. With no credential supplied, the CLI opens your browser to sign in with ID, captures the resulting user token, and saves your session to ~/.revenexx/prefs.json.

Shell
revenexx login

If a credential is already present — a --token flag, the REVENEXX_API_KEY environment variable, or a .revenexx.yaml file in the current directory tree — login uses that instead of opening the browser. A supplied key always takes precedence over the interactive flow, which keeps existing setups working unchanged.

For CI and scripts, pass a machine-to-machine API key and tenant directly so nothing needs a browser:

Shell
revenexx login --token <api-key> --tenant <slug>

login checks the key against that tenant and saves the key and endpoint, but not the tenant. Later commands still need a tenant from --tenant, REVENEXX_TENANT or .revenexx.yaml.

Both paths talk to https://api.revenexx.com/v1. A browser session sends its user token as Authorization: Bearer <token>; an API key rides as X-Revenexx-Api-Key. Either way the tenant travels as X-Revenexx-Tenant.

Credential resolution order

Any command that needs auth resolves its credentials the same way. The first source that has a value wins:

  1. CLI flag — --token, --endpoint, --tenant
  2. Environment variables — REVENEXX_API_KEY, REVENEXX_API_URL, REVENEXX_TENANT
  3. Project file — the nearest .revenexx.yaml, walking up from the current directory
  4. Global config — ~/.revenexx/prefs.json, written by revenexx login (either a browser session or a saved key)
  5. Built-in default — the endpoint defaults to https://api.revenexx.com/v1

A supplied key (sources 1–3) always wins over a stored browser session. The interactive browser sign-in only kicks in when you run login and none of those credential sources has a value — so CI never opens a browser.

The tenant slug has its own precedence: the --tenant flag, then the value set by tenants use (stored in ~/.revenexx/tenant), then REVENEXX_TENANT, then .revenexx.yaml.

That means one tenants use overrides REVENEXX_TENANT and every repo's .revenexx.yaml on your machine. Project configuration explains the trap and how to avoid it.

Select a tenant

tenants scopes your commands to one tenant. Set it once and every later command applies there.

Shell
revenexx tenants use <slug>

Run revenexx tenants use without a slug to pick from a list on a terminal (from CLI 0.6.1). In a script it prints the list and exits 1 instead of prompting.

Don't know your slug? revenexx tenants list shows the tenants your signed-in account can access — read from your browser-session token, no Cockpit visit needed. The line printed right after revenexx login names them too.

use checks the slug against the gateway first — with your API key when one is set, otherwise with your browser session — and refuses a tenant the gateway says you can't reach. Pass --force to set it anyway. In a script a refused slug prints the list of tenants and exits 1; on a terminal it opens the picker (from CLI 0.6.1). When the check itself can't run (no credential, an expired session, the gateway unreachable), use warns and saves the slug unchecked.

Check or list what's active:

Shell
revenexx tenants current
revenexx tenants current --check
revenexx tenants list
  • tenants current prints the saved slug from ~/.revenexx/tenant, or REVENEXX_TENANT when no slug is saved; --check verifies it against the gateway. With -q it prints the bare slug (from CLI 0.6.1); --json is not valid JSON, so don't pipe it to jq. It doesn't reflect --tenant or .revenexx.yaml, so on a terminal trust the banner above an API command for the tenant it actually uses.
  • tenants list shows the tenants your account can access (from the SSO session) plus the slugs the CLI can see from this shell and directory — from flags, environment, .revenexx.yaml, the saved slug, and API-key sessions — along with where each came from and whether your current credential can reach it. Its active marker follows the same rule as tenants current.

What's next

Was this page helpful?