> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/developer-tools/terra-cli/guardrails.md).

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

```bash
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:

```bash
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.

```bash
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.

```bash
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.

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