> 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/command-reference.md).

# Command reference

Every Terra CLI command group, the flags all commands share, and how to print the full reference from the CLI.

This page lists the command groups and the flags they share. For every command and flag with its full description, ask the CLI. That output is generated from the same source as the commands, so it cannot drift.

```bash
terra --help                    # the command groups
terra users list --help         # one command
terra reference                 # every command and flag, as one document
terra reference billing         # one group
terra reference --format json   # the same, with types, defaults, and enums
```

Commands follow the pattern `terra <group> [<sub-group>] <verb> [<argument>] [flags]`. Most groups use the verbs `list`, `retrieve`, `create`, `update`, and `delete`.

## Global flags

Every command accepts these.

| Flag                    | Purpose                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| `--profile <name>`      | Use this profile instead of the active one                        |
| `--color auto\|on\|off` | When to colorize output                                           |
| `-s`, `--show-headers`  | Trace requests and responses to stderr, with credentials redacted |
| `-h`, `--help`          | Help for the command                                              |

`terra --version` and `terra version` print the CLI version. `-v` works on the root command only.

## Common flags

Commands that call the API accept these where they apply.

| Flag                      | Purpose                                                                |
| ------------------------- | ---------------------------------------------------------------------- |
| `--env <name or dev-id>`  | Target environment. Defaults to `TERRA_ENV` or the configured default. |
| `--format <format>`       | Output format                                                          |
| `--select <fields>`       | Output only these response fields, comma-separated                     |
| `--jq <expression>`       | Filter the output with a jq expression                                 |
| `--dry-run`               | Print the request without sending it                                   |
| `--limit <n>`             | Page size, on list commands                                            |
| `--cursor <cursor>`       | Start a list from this cursor                                          |
| `--paginate`              | Collect pages into one document in the selected format                 |
| `--max-pages <n>`         | Cap `--paginate` at n pages. Default 10, and 0 for no limit.           |
| `-y`, `--yes`             | Skip the confirmation prompt on a destructive command                  |
| `--idempotency-key <key>` | Supply your own Idempotency-Key header                                 |
| `--no-retry`              | Do not retry retryable failures                                        |
| `--timeout <duration>`    | Request timeout. Default 30s.                                          |
| `--body <json>`           | Raw JSON request body, replacing the field flags                       |
| `--body-file <path>`      | Read the request body from a file, or `-` for stdin                    |

API commands support `json`, `table`, `ndjson`, `yaml`, and `csv`. Pagination preserves that choice and buffers the records before printing. Most request timeouts default to 30 seconds; Supabase provisioning defaults to 10 minutes. See [Output and scripting](/developer-tools/terra-cli/output-and-scripting.md).

A command that sends a body also takes one flag per body field, such as `--name` or `--url`. `terra <command> --help` lists them along with the scope the command needs. `terra help <command>` shows the same supported flags.

For a repeatable request flag, pass it once per value:

```bash
terra events list --provider GARMIN --provider FITBIT --destination-type webhook
```

For nullable body fields, the literal `null` clears the field. This also applies to nullable string arrays when `null` is their only value:

```bash
terra account update --phone-number null
terra company update-onboarding --providers null
```

The JSON reference includes required and repeatable parameters, enums, formats, nullability, schema constraints, and separate CLI and API defaults. Name a command to keep the reference focused:

```bash
terra reference events list --format json
```

## Core commands

| Command        | Description                                       |
| -------------- | ------------------------------------------------- |
| `terra login`  | Authenticate with Terra                           |
| `terra logout` | Revoke the stored token and forget it             |
| `terra whoami` | Show the identity and scopes of the current token |
| `terra config` | Read and change the CLI's configuration           |

## Product commands

### environments

Manage environments (dev-ids) and their credentials.

| Command                | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| `list`                 | List the account's environments                       |
| `retrieve`             | Environment detail, with secrets masked               |
| `create`               | Create the environment profile for an existing dev-id |
| `update`               | Update the environment's display fields               |
| `use <name or dev-id>` | Set the default environment for this profile          |
| `retrieve-api-key`     | Read the environment's API key (`keys:read`).         |
| `rotate-api-key`       | Rotate the environment's API key                      |

### unified-api

The Unified API product and the products built on it.

| Sub-group               | Commands                                                                                        | Description                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `sources`               | `list`, `enable <provider>`, `disable <provider>`                                               | Enable and configure wearable providers                            |
| `sources credentials`   | `retrieve <provider>`, `replace <provider>`                                                     | Your own OAuth credentials for a provider, used instead of Terra's |
| `sources scopes`        | `retrieve <provider>`, `replace <provider>`                                                     | Which data types a provider is asked for                           |
| `destinations`          | `list`, `create`, `update <destination_id>`, `delete <destination_id>`                          | Manage data destinations                                           |
| `destinations supabase` | `provision`, `start-oauth`, `poll-oauth <oauth_session_id>`, `list-projects <oauth_session_id>` | Supabase as a data destination                                     |
| `data scopes`           | `list`, `update`, `replace`                                                                     | Which fields Terra collects per data type                          |
| `data processing`       | `list`, `update`                                                                                | How Terra normalizes and derives each data type                    |
| `scores`                | `list`, `retrieve <score>`, `update <score>`                                                    | Configure and inspect scores                                       |
| `scores analytics`      | `retrieve`                                                                                      | Aggregate score results across an environment                      |
| `scores history`        | `list`                                                                                          | Score results over time for one user                               |
| `widget`                | `retrieve`, `update`                                                                            | Configure the Terra widget                                         |

### users

Inspect end-user connections.

| Command | Description                                                                   |
| ------- | ----------------------------------------------------------------------------- |
| `list`  | List end-user connections, with filters and pagination                        |
| `stats` | Connection and delivery metrics; `--view full` adds daily and provider detail |

### events

Inspect and resend webhook events.

| Command                       | Description                                                 |
| ----------------------------- | ----------------------------------------------------------- |
| `list`                        | Delivery history, filterable by outcome and user            |
| `retrieve <event_id>`         | Fetch a single delivery event                               |
| `retrieve-payload <event_id>` | The body an event carried, retained for about 14 days       |
| `stats`                       | Delivery metrics; `--view full` adds buckets and breakdowns |
| `resend`                      | Re-dispatch a stored event                                  |

### data-tokens

Manage data-plane tokens for an environment.

| Command                      | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `list`                       | List an environment's data tokens            |
| `create`                     | Mint a data token and print its credentials. |
| `delete <token_id>`          | Revoke a data token                          |
| `retrieve-secret <token_id>` | The signing secret behind a data token       |

### models

Inspect models and model runs.

| Command        | Description                      |
| -------------- | -------------------------------- |
| `catalog list` | Models available to this account |
| `runs list`    | Executions of a model            |

### workouts

Manage workout metadata.

| Command                          | Description                        |
| -------------------------------- | ---------------------------------- |
| `metadata list`                  | Custom fields attached to workouts |
| `metadata retrieve <workout_id>` | One workout's custom fields        |
| `metadata update <workout_id>`   | Update custom fields               |
| `metadata replace <workout_id>`  | Replace custom fields              |
| `metadata delete <workout_id>`   | Delete custom fields               |

## Account commands

### account

Inspect and update the token's own account record.

| Command             | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `retrieve`          | Inspect the current token, also available as `terra whoami` |
| `update`            | Update your own dashboard user profile                      |
| `retrieve-metadata` | Your analytics layout and preferences                       |
| `update-metadata`   | Update your analytics layout and preferences                |

### billing

Subscriptions, invoices, and usage.

| Command                           | Description                                |
| --------------------------------- | ------------------------------------------ |
| `subscriptions list`              | Plans this account is subscribed to        |
| `subscriptions create`            | Subscribe to a plan                        |
| `subscriptions cancel-incomplete` | Cancel a subscription that never completed |
| `invoices list`                   | Past invoices                              |
| `invoices upcoming`               | The next invoice                           |
| `payment-method retrieve`         | The card or bank account charged           |
| `usage retrieve`                  | Metered usage for the current period       |

### company

Manage the company record and onboarding.

| Command                    | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `retrieve`                 | Account summary                                    |
| `update`                   | Update the company profile                         |
| `retrieve-onboarding`      | Onboarding progress and the answers given          |
| `update-onboarding`        | Update onboarding answers                          |
| `list-feature-flags`       | Which features are turned on for this company      |
| `retrieve-terms <version>` | Terms of service acceptance                        |
| `agree-terms`              | Accept the terms of service                        |
| `retrieve-referral-code`   | The code this company shares to refer others       |
| `ensure-referral-code`     | Create a referral code                             |
| `retrieve-referrals`       | Companies that signed up through the referral code |
| `opt-in-points`            | Opt in to the rewards points programme             |

### entitlements

| Command | Description               |
| ------- | ------------------------- |
| `list`  | List feature entitlements |

### team

Manage team members.

| Command                              | Description                        |
| ------------------------------------ | ---------------------------------- |
| `members list`                       | People with access to this account |
| `members retrieve <user_id>`         | One member                         |
| `members update <user_id>`           | Change a member's role             |
| `members delete <user_id>`           | Remove a member                    |
| `invitations list`                   | Outstanding invitations            |
| `invitations create`                 | Invite someone                     |
| `invitations delete <invitation_id>` | Withdraw an invitation             |

### tokens

Manage admin tokens for this account.

| Command             | Description                                      |
| ------------------- | ------------------------------------------------ |
| `list`              | List the account's tokens                        |
| `rotate`            | Rotate the calling token within its grant window |
| `delete <token_id>` | Revoke a token by id                             |

## Additional commands

| Command                           | Description                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `terra docs ask --question "..."` | Ask a question and get an answer from the docs                                                                          |
| `terra api <path>`                | Send a request to any admin API endpoint. See [Raw API requests](/developer-tools/terra-cli/raw-requests.md).           |
| `terra api list [<path>]`         | List every endpoint and the command that covers it                                                                      |
| `terra data-api <path>`           | Send a request to any data API endpoint                                                                                 |
| `terra agent setup`               | Install Terra's agent skills into your coding agents. See [Coding agents](/developer-tools/terra-cli/coding-agents.md). |
| `terra reference [<command>]`     | Print every command and flag as one document                                                                            |
| `terra completion <shell>`        | Generate a completion script for bash, zsh, fish, or PowerShell                                                         |
| `terra version`                   | Show the CLI version                                                                                                    |