Project configuration

How the revenexx CLI is configured — the credential resolution order, the .revenexx.yaml project file, the global prefs.json and tenant files written by login and tenants use, and the environment variables that drive non-interactive runs.

The CLI reads its settings from a few places: flags, environment variables, an optional per-project .revenexx.yaml, and the global files it writes itself. There is no revenexx.json project file and no init step. Knowing which source holds what makes the CLI predictable across a local workspace and a CI pipeline.

How credentials resolve

Any command that needs auth resolves three values — a credential (an API key, or the user token saved by a browser SSO sign-in), the endpoint, and the tenant — from the first source that has them. The order:

CLI flag — --token, --endpoint, --tenant
Environment variables — REVENEXX_API_KEY, REVENEXX_API_URL, REVENEXX_TENANT
Project file — the nearest .revenexx.yaml, walking up from the current directory
Global config — ~/.revenexx/prefs.json, written by revenexx login
Built-in default — the endpoint defaults to https://api.revenexx.com/v1

The tenant slug has its own order: --tenant, then ~/.revenexx/tenant (set by tenants use), then REVENEXX_TENANT, then .revenexx.yaml. See Authentication for the full picture.

One tenants use overrides every repo. The slug it saves in ~/.revenexx/tenant beats REVENEXX_TENANT and the tenant: in every .revenexx.yaml. In the credential order above, a file in your home directory comes last; for the tenant it comes second. It applies to your user account on that machine, in every shell and every project. From CLI 0.6.1, tenants use warns at the moment you run it when the slug it saves overrides the environment variable or the project file, but it still overrides them. A script that exports REVENEXX_TENANT=staging never runs use, so it gets no warning and still goes to the tenant you last chose with use. On an interactive terminal, API commands print a banner naming the tenant actually used (not with --json or --quiet).

Pass --tenant <slug> when a command must hit a specific tenant. The flag beats the saved slug (CLI 0.5.0 or later).
Delete the file to clear it. The CLI has no command that unsets the saved slug; rm ~/.revenexx/tenant hands control back to REVENEXX_TENANT and .revenexx.yaml.
Then keep a tenant: per repo instead of running tenants use when you switch between client projects. It only applies while neither the saved slug nor REVENEXX_TENANT is set.

Configuration files

File	Scope	Holds
`.revenexx.yaml`	Project (nearest, walking up)	Endpoint, API key (`token:`), tenant, and the `defaultMode` for this workspace. You write this by hand; it's read during credential resolution.
`~/.revenexx/prefs.json`	Global (per machine)	Saved login session and endpoint, written by `revenexx login` — either a browser SSO session or a saved key.
`~/.revenexx/tenant`	Global (per machine)	The active tenant slug, written by `revenexx tenants use`. Overrides `REVENEXX_TENANT` and every `.revenexx.yaml` — see the warning above.

A .revenexx.yaml lets you commit per-project context (endpoint and tenant) to a repo and keep the key in the environment. A minimal one:

.revenexx.yaml

apiUrl: https://api.revenexx.com/v1
tenant: acme
# token: rvxk_...     # prefer REVENEXX_API_KEY in the environment for secrets
# defaultMode: tui    # tui (default) | guided | help — see Default mode below

Don't use the client command to set these defaults on a new machine. client --endpoint rejects the public endpoint, and client --key fails until a session exists. Sign in with revenexx login, or set the environment variables or .revenexx.yaml instead.

Environment variables

For CI and scripts, set credentials in the environment instead of files. These override the config files during credential resolution:

Variable	Sets
`REVENEXX_API_KEY`	The gateway API key (the token used to authenticate).
`REVENEXX_API_URL`	The API endpoint. Defaults to `https://api.revenexx.com/v1`.
`REVENEXX_TENANT`	The tenant slug.
`REVENEXX_SENSITIVE_TENANTS`	Comma-separated list of tenant slugs always treated as production (same as `revenexx client --sensitive-tenants`).
`REVENEXX_NO_TUI`	Set to `1` (any value other than `0`/`false`) to stop a bare `revenexx` from launching the full-screen app — see Default mode.

Default mode

On an interactive terminal, a bare revenexx — with no command and no --json or --help — launches the full-screen app (TUI) by default. Two settings change what that bare invocation does; explicit subcommands (repl, tui, any service command) always win regardless of either.

Source	Value	Effect
`REVENEXX_NO_TUI` env var	`1` / any value other than `0`/`false`	A bare `revenexx` falls back to the guided picker.
`defaultMode:` in `.revenexx.yaml`	`tui`	A bare `revenexx` launches the full-screen app (the default).
	`guided`	A bare `revenexx` opens the guided command picker.
	`help`	A bare `revenexx` prints usage and exits.

REVENEXX_NO_TUI takes precedence over the config file, and both apply only to an interactive terminal — a pipe, CI, --json, or --help always prints help and never opens an interactive surface.

.revenexx.yaml

defaultMode: guided

What's next

Run the CLI non-interactively with these variables.
Look up every global command in the global commands reference.

Was this page helpful?