Guardrails

Preview changes, understand credential output, and use confirmation prompts, idempotency keys, retries, and timeouts.

The admin API can reveal credentials and delete things. A few operations therefore need more than typing them.

Preview a request

--dry-run asks the API to preview a change without committing it. It requires credentials, the operation's scopes, and a network connection. Check the command's --help for the flag: only operations with preview support offer it.

terra environments update --env dev-prod --name Acme --dry-run

The CLI sends the request with dry_run=true. Output includes the API's dry_run, would, and preview fields. Tables show preview as a nested section. Use --select to pick fields from the preview, or --jq without --select to query the full response:

terra environments update --env dev-prod --name Acme --dry-run --select name
terra environments update --env dev-prod --name Acme --dry-run --jq .preview

Previews skip destructive confirmation and send no idempotency key, even if --idempotency-key is supplied. API failures use the normal exit codes.

Commands without preview support, including terra admin-api and terra data-api, reject --dry-run. There is no offline request printer. Use --help or terra reference to inspect a command without credentials.

Credential output

Credential endpoints print the credential material the API returns. Reading an environment API key needs keys:read, which the default login does not grant.

terra login --scope keys:read
terra environments retrieve-api-key

terra environments rotate-api-key, terra tokens rotate, terra data-tokens create, and terra data-tokens retrieve-secret can also return secrets. Choose where their output goes before running them. --select can limit the response fields you print, but does not change what the API returns.

Request tracing with --show-headers redacts credentials and reports body sizes instead of bodies. Normal command output still includes returned credentials.

Destructive commands

Destructive commands confirm first. They show the environment, target IDs, and the operation's warning. The customer ID is shown when it is stored in the profile's token metadata. Enter yes to confirm.

These include deletes, API key and personal access token rotation, subscription changes, and data-scope updates that clear omitted fields. Read the command's --help for the effect and required scope.

The environment is shown because it may have come from configuration or TERRA_ENV, in which case it is invisible in the command you typed.

Where there is no terminal to ask, in CI or under an agent, the command refuses rather than guessing. Pass --yes (or -y) to proceed.

terra unified-api destinations delete dest_123 --yes

Declining a prompt exits with code 7, so terra tokens delete tok_1 && echo deleted does not print deleted after a decline.

Idempotency

Mutations carry an Idempotency-Key header automatically where the API accepts one, and reuse it across retries, so a retried request cannot double-apply. Supply your own with --idempotency-key to make a retry safe across separate invocations.

The flag appears only on commands whose endpoint honors the header, so terra <command> --help tells you. terra admin-api never generates a key, because it cannot know whether the endpoint deduplicates.

Retries and timeouts

Requests are retried only when replaying them is safe: idempotent methods, or any request carrying an idempotency key. The CLI honors Retry-After when the server sends it. Disable retries with --no-retry.

--timeout bounds a single request and must be positive. Most commands default to 30 seconds; Supabase provisioning defaults to 10 minutes. Check the command's help for its default.

terra environments list --timeout 5s --no-retry