> 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/terra-cli.md).

# Overview

Everything the [dashboard](https://dashboard.tryterra.co) does, from the terminal: environments, credentials, providers, webhooks, users, and event replay. Your coding agent can run it too. See [Coding agents](/developer-tools/terra-cli/coding-agents.md).

## Get started

{% stepper %}
{% step %}

### Install, log in, set up your agent

```bash
brew install tryterra/tap/terra   # macOS
npm install -g @tryterra/cli      # everywhere else
terra login
terra agent setup
```

`terra agent setup` installs the Terra skills into the coding agents on your machine. See [Coding agents](/developer-tools/terra-cli/coding-agents.md). In CI, set `TERRA_ADMIN_TOKEN` instead of logging in. See [Authentication](/developer-tools/terra-cli/authentication.md).
{% endstep %}

{% step %}

### Pick an environment

```bash
terra environments use Production
```

Saves passing `--env` on every command.
{% endstep %}

{% step %}

### Run a command

```bash
terra users list
```

Output is a table on a terminal and JSON when piped. See [Output and scripting](/developer-tools/terra-cli/output-and-scripting.md).
{% endstep %}
{% endstepper %}

## Common tasks

### Set up an environment

```bash
terra unified-api sources enable GARMIN
# Garmin appears in the auth widget and starts syncing to your destinations

terra unified-api destinations create --type webhook --url https://example.com/hook
# prints the new destination's id

terra environments api-key retrieve --reveal
# prints the dev-id, API key, and webhook signing secret
```

### Send a user through auth, then check it worked

```bash
terra data-api /auth/generateWidgetSession -X POST -d reference_id=user-42
# returns a widget URL to open for the user

terra users list --reference-id user-42
# one row per connection: user id, provider, active, created at

terra events list --reference-id user-42 --data-type auth
# the auth event, with a message if it failed
```

### Find out why a webhook never arrived, and resend it

```bash
terra events list --user-id <uuid> --outcome failed
# one row per failed delivery: event id, data type, provider, HTTP status, sent at

terra events payload retrieve <event_id>
# the body Terra tried to send

terra events resend --event-id <event_id> --event-type sleep --user-id <uuid>
# sends it to your destination again
```

### Pull a user's data

```bash
terra data-api /sleep -q user_id=<uuid> -q start_date=2026-08-01 -q to_webhook=false
# sleep sessions as JSON, printed here instead of sent to your destination
```

Drop `to_webhook=false` to send the data to your destination instead, which is how you backfill a new user's history.

### Rotate an API key

```bash
terra environments api-key rotate --reveal
# prints the new key; the old one stops working immediately
```

### Turn on a health score and read the results

```bash
terra unified-api scores update readiness --active true
# readiness scores appear in payloads for users with eligible data

terra unified-api scores history list --score readiness --user-id <uuid>
# one row per computed score: value, time window, provider
```

### Push a planned workout to a user's device

```bash
terra data-api /workouts -X POST --body-file workout.json
# returns the workout_id

terra data-api /workouts/<workout_id>/plan -X POST -d user_id=<uuid>
# schedules it on the user's device; prints the planned workout id and any coercion warnings
```

### Check where a lab report was delivered

```bash
terra data-api /lab-reports/<session_id>
# the session's status and its parsed results

terra data-api /lab-reports/<session_id>/deliveries
# one row per destination: status, attempt count, last error
```

### Ask the docs

```bash
terra ask "how do I verify a webhook signature?"
# an answer with links to the docs pages it came from
```

See [Ask the docs](/developer-tools/terra-cli/ask.md).

## Find a command

`terra --help` lists the groups, `terra <command> --help` describes one, and `terra reference` prints everything. See [Command reference](/developer-tools/terra-cli/command-reference.md).

## Safe by default

* `--dry-run` prints the request and sends nothing.
* Credentials in a response stay hidden without `--reveal`.
* Destructive commands confirm first, or need `--yes` without a terminal.

See [Guardrails](/developer-tools/terra-cli/guardrails.md).

## Get help

Open a [GitHub issue](https://github.com/tryterra/terra-cli/issues) with the output of `terra version` and the failing command run with `--show-headers`. Credentials are redacted. Account, billing, and contract questions go to your Terra support channel, not the public tracker.

{% hint style="danger" %}
Security issues: follow the [security policy](https://github.com/tryterra/terra-cli/security/policy), not a public issue.
{% endhint %}