> 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/coding-agents.md).

# 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](/developer-tools/agent-skills.md#install). 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](/developer-tools/agent-skills.md) 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

```bash
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](/developer-tools/terra-cli/terra-cli.md#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](/developer-tools/terra-cli/guardrails.md).

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

```bash
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](/developer-tools/terra-cli/authentication.md).

**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](/developer-tools/terra-cli/output-and-scripting.md).

**Preview before acting.** `--dry-run` prints the request and sends nothing.

**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](/developer-tools/terra-cli/ask.md).