> 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`               | Ask the API to preview a change on supported commands                  |
| `--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                    |

`--dry-run` requires credentials and a network connection. Commands without preview support reject it. See [Guardrails](/developer-tools/terra-cli/guardrails.md#preview-a-request).

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 update` | Update the CLI using its original installation method |
| `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               |

`terra update` updates supported installations to the latest stable release. See [Installation](/developer-tools/terra-cli/installation.md#updates) for automatic updates and opt-outs.

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

`subscriptions create` accepts `monthly` or `annual` for `--schedule`; the `startup` plan requires it. Subscription changes require `billing:write`. When payment confirmation is needed, open the response's `payment_url` to complete it. Use `--select payment_url` to print only that link.

Both `subscriptions create` and `subscriptions cancel-incomplete` support `--dry-run` to preview the change without committing it.

### 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 personal access tokens for this account. See [Personal access tokens](https://docs.tryterra.co/reference/admin-api/personal-access-tokens).

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

## Example apps

Discover and download complete Terra integrations. These commands fetch the current public catalog over the network and need no Terra login or selected environment. See [Example apps](/developer-tools/example-apps/example-apps.md) for the app guides.

| Command                                      | Description                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| `terra examples list`                        | List published apps with their names, titles, and descriptions          |
| `terra examples clone <example> [directory]` | Download an app into a new directory and return its path and next steps |

```bash
terra examples list
terra examples clone unified-api-web-app my-app
```

`<example>` is a name from `terra examples list`. The destination defaults to that name when omitted. Its parent must exist, and the destination must not exist, even as an empty directory. Files and package names are preserved as published. Cloning only downloads files: follow the app's README to install dependencies and configure it. The download itself needs neither Node.js nor Git.

Both commands support `--format`, `--select`, and `--jq`. Output is a table on a terminal and JSON when piped. See [Output and scripting](/developer-tools/terra-cli/output-and-scripting.md).

```bash
terra examples list --select name,title
terra examples list --jq '.[].name'
terra examples clone streaming-mobile-app my-mobile-app --jq .path
```

If a download fails after creating the destination, partial files remain at the reported path.

## Additional commands

| Command                           | Description                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `terra docs ask --question "..."` | Ask a question and get an answer from the docs                                                                          |
| `terra admin-api <path>`          | Send a request to any admin API endpoint. See [Raw API requests](/developer-tools/terra-cli/raw-requests.md).           |
| `terra admin-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                                                                                                    |