Authentication

Log in to the Terra CLI interactively, from CI, or without a browser, and manage the token it stores.

The CLI authenticates with a personal access token for your Terra account. There are three ways to supply one.

Situation	Use
Your own machine	terra login
CI, or any other non-interactive environment	The TERRA_ADMIN_TOKEN environment variable
A machine with no browser, or a coding agent	terra login --start, then terra login --complete

Interactive login

terra login

The CLI prints a pairing code and opens the dashboard to approve it. Once approved, the token is stored in your OS keyring. Only non-secret metadata, such as the token id, scopes, and expiry, goes in the config file.

By default the token receives every non-dangerous admin scope. Scopes that expose credentials or change billing and team membership, such as keys:read, tokens:admin, billing:write, and team:write, are excluded unless you ask for them:

terra login --scope keys:read --scope providers:write

--scope requests a specific set of admin scopes, rather than adding to the default set. Data API scopes cannot be granted by terra login; use terra data-tokens create for those. terra login --help lists grantable scopes and marks dangerous ones.

Restrict a token to one environment with --env:

terra login --env dev-prod

Pass --no-browser to print the verification URL instead of opening it.

CI

Set TERRA_ADMIN_TOKEN and skip terra login. Every command uses the variable, and nothing is written to the config file or the keyring.

export TERRA_ADMIN_TOKEN=terra_at_...
terra environments list

Without a browser

When the process cannot stay open while a human approves in a browser, split the login in two.

terra login --start

{
  "user_code": "TERRA-K7MP-4WX2",
  "verification_uri": "https://dashboard.tryterra.co/cli/verify",
  "verification_uri_complete": "https://dashboard.tryterra.co/cli/verify?code=TERRA-K7MP-4WX2",
  "device_code": "1a2b3c4d",
  "expires_in": 900,
  "interval": 5,
  "next_step": "terra login --complete 1a2b3c4d"
}

Open verification_uri_complete in any browser and approve the pairing. Then run the next_step command. It waits for the approval and stores the token.

--start stores nothing. There is no token until the pairing is approved.

Token lifetime

Tokens from terra login expire after 30 days. Extend one with terra tokens rotate. Rotation works until the 90-day grant window closes, and after that you log in again.

Rotation invalidates the current token and prints its replacement once. Save that token value and supply it through TERRA_ADMIN_TOKEN. The rotation command does not update the CLI's stored credential. To replace the stored credential through the login flow, run terra login again.

The API sets both windows, not the CLI. terra whoami reports the expiry the server issued.

For unattended access to the data API, mint a data token rather than scripting a login:

terra data-tokens create --env dev-prod --name ci --scopes auth:write

Where the token is stored

In the OS keyring, keyed by profile. When no keyring is available, the CLI falls back to a file with mode 0600 in the config directory and says so. Set TERRA_KEYRING=file to force the file.

terra config --list shows the token metadata and which backend is in use. The config file never holds a token.

Check who you are

terra whoami
terra whoami --format json

terra whoami runs the same operation as terra account retrieve. The response includes the token's token_id, kind, customer_id, scopes, dev_ids, and expires_at. The user object requires account:read; without that scope it is null. Missing or rejected credentials exit with code 2.

Log out

terra logout

This revokes the stored token server-side and removes it locally. If the revocation fails, the local credential is still removed, and the CLI says so.

A token supplied through TERRA_ADMIN_TOKEN is not stored, so terra logout does not revoke it. Unset the variable instead.