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.
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 enumsCommands 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.
--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.
--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.
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.
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:
For nullable body fields, the literal null clears the field. This also applies to nullable string arrays when null is their only value:
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:
Core commands
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 for automatic updates and opt-outs.
Product commands
environments
Manage environments (dev-ids) and their credentials.
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.
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.
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.
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.
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.
catalog list
Models available to this account
runs list
Executions of a model
workouts
Manage workout metadata.
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.
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.
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.
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
list
List feature entitlements
team
Manage team members.
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.
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 for the app guides.
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
<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.
If a download fails after creating the destination, partial files remain at the reported path.
Additional commands
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.
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.
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
Last updated
Was this helpful?