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

# 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:

# 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:

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:

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:

  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:

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:

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.

# 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 — create test and live keys in the dashboard.
• Environments overview — the customer environment model.
• CLI install and core commands — the rest of the CLI surface.