> ## Documentation Index
> Fetch the complete documentation index at: https://uiform-codex-generated-frontend-snippets.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI environments

> Manage local CLI profiles for test, production, and custom environments

The Retab CLI stores named environment profiles in `~/.retab/config.json`.
Each profile pairs a slug (`test`, `production`, `staging`, `qa`, ...)
with a stored API key. CLI commands resolve credentials from those
profiles, environment variables, and flags using a strict precedence so
the command target is never ambiguous.

The key still selects the customer environment. CLI profile flags only
choose which stored key the CLI sends.

## Commands

```bash theme={null}
# Add the two canonical environments.
retab env add test       --api-key rt_test_...
retab env add production --api-key rt_live_...

# Add custom environments. Their "type" is inferred from the key prefix
# (rt_test_ -> test, rt_live_ -> production).
retab env add staging --api-key rt_test_...
retab env add qa      --api-key rt_test_...
retab env add demo    --api-key rt_test_...

# Inspect what is configured locally.
retab env list
retab auth status

# Change the default profile used when no per-command override is given.
retab env switch test
retab env switch staging
retab env switch production

# Remove a profile.
retab env remove staging
```

`retab env switch` only changes the local default. It never mutates server
state and it never changes what an API key can access.

## Selecting an environment for one command

Three flags pick an environment for a single command:

```bash theme={null}
# Named environment from your local profiles.
retab workflows list --env staging

# Shortcut for --env production.
retab workflows list --live

# Explicit key override (highest precedence).
retab workflows list --api-key rt_test_...
```

`--live` is documented as an alias for `--env production`. It always
targets the canonical production environment, regardless of any custom
display name you give production locally.

## Resolution precedence

The CLI picks credentials in this strict order. The first source that
provides a key wins.

| # | Source                                                          |
| - | --------------------------------------------------------------- |
| 1 | `--api-key` flag                                                |
| 2 | `RETAB_API_KEY` environment variable                            |
| 3 | `--env <slug>` stored environment profile                       |
| 4 | `--live` stored production profile                              |
| 5 | Stored `default_environment` profile (e.g. set by `env switch`) |
| 6 | Stored OAuth session (for commands that support it)             |
| 7 | Legacy stored `api_key`                                         |
| 8 | Unauthenticated error                                           |

## Conflict rejection

The CLI rejects combinations where the visible command target and the
actual key target could disagree. This is deliberate: silent overrides
are exactly how production accidents happen.

| Input                                                 | Behavior                                            |
| ----------------------------------------------------- | --------------------------------------------------- |
| `--api-key` + `--live`                                | Fails: the key already selects the environment.     |
| `--api-key` + `--env <slug>`                          | Fails: the key already selects the environment.     |
| `RETAB_API_KEY` + `--live`                            | Fails: env var key already selects the environment. |
| `RETAB_API_KEY` + `--env <slug>`                      | Fails: env var key already selects the environment. |
| `--env production` + `--live`                         | Accepted (equivalent).                              |
| `--env test` + `--live`                               | Fails as contradictory.                             |
| Stored profile key resolves to a different server env | Fails; re-add the profile with the right key.       |

Sample error:

```text theme={null}
error: --live cannot be combined with RETAB_API_KEY; the key already
selects the environment
```

## Server-resolved environment

`retab auth status` reports what the server says about the active
credential, not just what the prefix looks like:

```text theme={null}
authenticated: true
base_url: https://api.retab.com
default_environment: test
active_credential: rt_test_...abcd
resolved_environment: test

configured environments:
  test          rt_test_...abcd   valid
  staging       rt_test_...stg1   valid
  production    rt_live_...wxyz   valid
```

`retab env list` shows the same picture in a table:

```text theme={null}
  Name          Type         Active  Credential
  test          test         yes     rt_test_...abcd
  staging       test         no      rt_test_...stg1
  production    production   no      rt_live_...wxyz
```

JSON output is available for scripts (add `--json` or rely on the
non-TTY default).

## Production safety prompts

High-risk live writes (publish, delete, rotate secret, run with external
side effects, retry job, resend webhook) require confirmation. In an
interactive shell the CLI prints:

```text theme={null}
You are about to modify Retab production.

environment: production
credential: rt_live_...wxyz
command: workflows publish wf_...

Type "production" to continue:
```

In a non-interactive shell — CI, scripts, agent runs — confirmation is
not available, so the CLI requires `--confirm`:

```text theme={null}
error: production write requires --confirm in non-interactive mode
```

Read-only commands (`list`, `get`, `auth status`, `diagnose`, ...) never
prompt; they print the resolved environment in debug/status output so
the target is still visible.

## CI guidance

Prefer **explicit keys** plus `--confirm` over ambient `env switch
production` in CI. The explicit form makes production use visible in
the script and in CI logs, and it avoids the failure mode where a
forgotten `env switch` silently turns subsequent commands into
production writes.

```bash theme={null}
# CI tests
RETAB_API_KEY=rt_test_... retab workflows tests runs create wf_...

# CI production deploy / publish
RETAB_API_KEY=rt_live_... retab workflows publish wf_... --confirm
```

Do not recommend `retab env switch production` in a CI runner.

## Custom environments

Custom slugs (e.g. `staging`, `qa`, `demo`) are local profile names. Each
custom slug is still backed by a test or production API key, so its
server-side type is determined by the key:

* `rt_test_...` -> server type `test`
* `rt_live_...` -> server type `production`

This keeps the two important safety classes (test vs. production) intact
while letting you organize multiple credentials under names that match
your own infrastructure.

## See also

* [API keys](/environments/api-keys) — create test and live keys in the dashboard.
* [Environments overview](/environments/overview) — the customer environment model.
* [CLI install and core commands](/overview/CLI) — the rest of the CLI surface.