> 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 requests, 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` prints the request a command would send, and sends nothing. It is available on generated API commands, `terra api`, and `terra data-api`, and needs no credential.

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

```json
{
  "dry_run": {
    "method": "PATCH",
    "url": "https://access.tryterra.co/api/v3/admin/environments/dev-prod",
    "body": { "name": "Acme" },
    "headers": {
      "Accept": ["application/json"],
      "Authorization": ["Bearer ***"],
      "Content-Type": ["application/json"],
      "Idempotency-Key": ["1485dc8e-9073-46ce-8bd9-ca6069f7b6ce"],
      "User-Agent": ["terra-cli/1.0.0 (darwin; arm64)"]
    }
  }
}
```

Use it to check that a command resolved the environment you expect and built the body you meant. `--select` is refused alongside `--dry-run`, because it selects fields of a response. Use `--jq` to filter the preview.

Header values are redacted except for the ones the CLI sets itself. `Authorization` keeps its scheme so you can see which auth was attempted. Any header you add with `-H` prints as `***`.

{% hint style="info" %}
A dry run shows the request, not its effect. A few endpoints, such as deleting a destination or rotating an API key, accept a `dry_run=true` query parameter so the API can report what would change. Reach that with `terra api`:

```bash
terra api /environments/dev-prod/unified-api/destinations/dest_123 -X DELETE -q dry_run=true
```

{% endhint %}

## 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 admin 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 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
```