Terra CLI

Set up and debug your Terra integration from the terminal. Create environments and credentials, turn providers on and off, see which users have connected, and replay the webhook events your integration received. terra data-api reaches the data API too, for the wearable data itself and the user-linking flow.

Your coding agent can drive it too, so you can ask for the result instead of looking up the command. See Let your agent drive it.

The documentation is at docs.tryterra.co/developer-tools/terra-cli.

Get started

1. Install the CLI:

   Native Install (macOS and Linux):

   curl -fsSL https://cli.tryterra.co/install.sh | sh

   Installs into ~/.local/bin and configures PATH for Bash, Zsh, or fish. If prompted, open a new terminal or run the printed PATH command before logging in. Rerun the installer to update; add -s -- --help after sh for options.

   Native Install (Windows PowerShell, x64 or ARM64):

   irm https://cli.tryterra.co/install.ps1 | iex

   Requires Windows PowerShell 5.1 or PowerShell 7. Installs into %LOCALAPPDATA%\Terra\bin and adds it to your user and current session PATH. No administrator privileges are needed.

   Homebrew (macOS):

   brew install tryterra/tap/terra

   npm (all platforms):

   npm install -g @tryterra/cli

   On Windows ARM64, use ARM64 Node.js for a native npm installation.

2. Log in:

   terra login

   This opens your browser and prints a pairing code to approve in the dashboard.

3. Pick an environment and read something:

   terra environments list
   terra environments use Production
   terra users list

4. Ask a question when you are not sure:

   terra docs ask --question "how do I generate an auth widget"

   Answered from the documentation, with links to the pages it came from.

5. Find any other command:

   Search command names and descriptions, including nested commands:

   terra help --search webhook

   Or read the full reference:

   terra reference

   Every command and flag as one page. Name a group to narrow it: terra reference billing. Both terra <command> --help and terra help <command> list every supported flag for that command.

Stay up to date

Terra automatically updates Native Installs, global npm, and Homebrew installations. An invocation can start a background check once every four hours. Your command does not wait for the check or installation, and subsequent invocations use the updated version. Coding agents can trigger updates; CI does not.

To update explicitly, run terra update. On Windows, this schedules the update after the command exits. Run terra version to check the version your shell uses.

Project dependencies, npx, and pinned Homebrew installations are not changed automatically. Other installation methods receive manual update instructions. Updates never request elevated permissions.

Set TERRA_NO_AUTO_UPDATE=1 to keep update notices without installing updates. Set TERRA_NO_UPDATE_NOTIFIER=1 or DO_NOT_TRACK=1 to disable automatic update activity entirely. These settings do not prevent an explicit terra update.

Let your agent drive it

Terra configuration usually means clicking around the dashboard, which your agent cannot do. Give it the CLI instead. Paste this into Claude Code, Cursor, Codex or whatever you use:

Set up the Terra API CLI for this project. Install it with
"brew install tryterra/tap/terra" on macOS, or "npm install -g @tryterra/cli"
otherwise. Then run "terra agent setup" to install Terra's agent skills, read
the terra-cli skill it writes, and follow its getting-started section to tell
me what my account is configured to do.

That installs the skills into whichever agent is asking, so your agent then knows the commands, the exit codes, and the traps worth avoiding. In a later session, once it has picked the skills up, this is enough:

Get started with Terra API.

It will check that the CLI is authenticated, find your environments, report which wearable providers are on and where webhooks are going, and name the gap that matters. Then ask for whatever you need:

Which wearable providers are enabled in my dev environment, and where are its
webhooks going?

A sleep webhook never arrived for user 8f2a1c. Find out what Terra actually
delivered, and resend it.

Set up a staging environment with Garmin and Fitbit turned on, and point its
webhooks at my tunnel.

Asking questions is safe: reading changes nothing, and a delete refuses to run unattended rather than guessing that you meant it.

Before you change anything

Commands that support previews offer --dry-run. It sends an authenticated request to the API, which reports what would change without committing it. Commands without preview support reject the flag.

terra environments update --name Acme --dry-run

Destructive commands confirm first, naming the account and environment they will act on and what you cannot take back, and need --yes where there is no terminal to ask. These include deletes and commands that charge a card, rotate a live credential, or clear fields you leave out.

On a terminal, nested objects appear as sections and arrays of records as tables. Wide automatic tables fall back to stacked records. Use --format json for structured output in scripts.

Documentation

The CLI section of Terra's documentation covers the whole tool:

• Installation for Homebrew, npm, staying up to date, and shell completion
• Authentication for logging in interactively, in CI, or with no browser
• Configuration for environments, profiles, and every variable
• Output and scripting for formats, field selection, pagination, exit codes
• Guardrails for the dry run, secret gating, and confirmations
• Raw API requests for reaching an endpoint that has no command of its own
• Coding agents for driving the CLI from an agent
• Ask the docs for asking a question from the terminal
• Command reference for every command group and the flags they all share

What changed

Every released version, newest first, is in the changelog. terra version says which one you are on.

Reporting bugs

Found a security issue? Do not open a public issue. See the security policy, which routes it privately.

For everything else, use GitHub issues. Including terra version and the failing command with --show-headers helps: that traces the request with credentials redacted and bodies reduced to a byte count, so the output is safe to paste. Exit codes are a contract, documented in docs/troubleshooting.md.

For anything specific to your account, billing, or covered by your contract, use your usual Terra support channel instead. That tracker is public.

The CLI is built from a private repository, so a pull request here has nothing to change and cannot be merged. Open an issue instead.

Data collection, usage, and retention

Released builds report which commands are run, never flag values or arguments, so we can tell which parts of the CLI matter and which are getting in the way. docs/telemetry.md lists every field that is sent and every one that is not. To turn it off:

export TERRA_CLI_TELEMETRY_OPTOUT=1

DO_NOT_TRACK=1 works too, and is honored across tools that follow the convention.

For full details, see Terra's Terms of Service and Privacy Policy.