Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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
2RETAB_API_KEY environment variable
3--env <slug> stored environment profile
4--live stored production profile
5Stored default_environment profile (e.g. set by env switch)
6Stored OAuth session (for commands that support it)
7Legacy stored api_key
8Unauthenticated 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.
InputBehavior
--api-key + --liveFails: the key already selects the environment.
--api-key + --env <slug>Fails: the key already selects the environment.
RETAB_API_KEY + --liveFails: env var key already selects the environment.
RETAB_API_KEY + --env <slug>Fails: env var key already selects the environment.
--env production + --liveAccepted (equivalent).
--env test + --liveFails as contradictory.
Stored profile key resolves to a different server envFails; 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