Coding agents

Give a coding agent the Terra CLI so it can configure and debug your integration instead of asking you to click through the dashboard.

Terra configuration usually means clicking through the dashboard, which a coding agent cannot do. The CLI gives the agent the same actions as commands, so you can ask for a result instead of looking up how to get it.

Set up

If you use Claude Code, Codex or Cursor, install the Terra API plugin. It includes the skills, and the agent offers to install the CLI and log you in if either is missing.

For any other agent, paste this:

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.

terra agent setup installs Terra's agent skills into the agents this project uses. The terra-cli skill teaches the agent the commands, the exit codes, and the guardrails. Most agents load skills at startup, so once the skills are installed, a later session needs only:

Get started with Terra API.

The agent checks that the CLI is authenticated, finds your environments, reports which providers are on and where webhooks go, and names the gap that matters.

Setup options

terra agent setup --status-only        # report without writing
terra agent setup --client cursor      # one agent
terra agent setup --skills terra-cli,terra-unified-api
terra agent setup --global             # for this user, not this project
terra agent setup --format json        # machine-readable report

When an agent runs the command, it sets up that agent only. Otherwise the CLI looks for the agents the project already uses, then the agents installed on the machine. Where that leaves a choice, it names the candidates rather than guessing. Pass --client to pick one or --all for every agent it knows.

Things to ask

Anything in the CLI's common tasks works as a prompt:

Enable Garmin and Fitbit in my staging environment and point its webhooks at my tunnel URL.

Send user-42 through Terra auth and tell me whether the connection came back active. If not, find the failure message.

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

Pull the last week of sleep data for user 8f2a1c and show me the payload shape.

Create a 5x1km interval workout template and plan it onto user 8f2a1c's Garmin for tomorrow.

Lab report session 297405620317847552 never reached my webhook. Check its delivery outcomes.

Credential endpoints print the secrets the API returns. Destructive commands need --yes without an interactive terminal. See Guardrails.

How the CLI supports agents

This section is for anyone writing agent instructions or tooling directly.

Discovery in one call. terra reference --format json describes every command and flag, with argument and flag types, required and repeatable values, enums, formats, and schema constraints, so one read replaces a walk of --help. Name a group to read a fraction of the tokens.

terra reference billing --format json
terra reference --format json | jq '.. | select(.path? == "terra users list") | .flags'

The JSON reference declares schema_version. In a scoped reference, shared flags are in the root node's global_flags. Request parameters include their wire names and locations. cli_default describes a CLI default; api_default describes a default applied by the API when the parameter is omitted. A flag with multiple request locations carries a bindings array. Ignore unfamiliar fields when consuming the reference.

Authentication without a browser. Set TERRA_ADMIN_TOKEN, or use the two-step terra login --start and terra login --complete flow. See Authentication.

Machine-readable output. Piped API output is JSON. --paginate collects pages into one document and preserves --format; use --format ndjson for one record per line. terra whoami returns the account API response. Exit codes are a contract. See Output and scripting.

Preview before acting. On supported commands, --dry-run sends an authenticated API request that reports what would change without committing it. It requires the operation's scopes. Check --help for support, then inspect the preview before running the command without --dry-run. See Guardrails.

Automatic updates. Agent commands can trigger background updates on supported installations. Set TERRA_NO_AUTO_UPDATE=1 to keep notices without installing updates. CI does not trigger automatic updates. See Installation.

Agent detection. The agent's name is added to the User-Agent header so server-side triage can tell agent traffic apart. Help output is identical either way.

Ask the docs

An agent that is unsure is better off asking than guessing from training data. terra docs ask --question "..." --format json returns an answer, confidence, and sources from Terra's published documentation. Check sources to see whether the answer is grounded in the docs. See Ask the docs.