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

# Ask the docs

Ask a question about Terra from the terminal and get an answer from the documentation, with the pages it came from.

`terra docs ask` answers questions from Terra's published documentation and returns the pages the answer came from.

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

The command needs an authenticated CLI, but no specific scope. Run `terra login` or set `TERRA_ADMIN_TOKEN`. See [Authentication](/developer-tools/terra-cli/authentication.md).

## Ask a question

Pass the question with `--question`, quoting it so the shell keeps it together. Questions can contain up to 4,000 characters.

```bash
terra docs ask --question "how do I verify a webhook signature?"
terra docs ask --question "which providers support sleep data"
terra docs ask --question="--paginate stops after ten pages, how do I raise it?"
```

Your question is sent to Terra. CLI usage telemetry does not collect flag values or request bodies.

## Read the answer and sources

Output is a table on a terminal and JSON when piped. To print just the answer as Markdown, use `--jq`:

```bash
terra docs ask --question "how do I generate an auth widget" --jq '.answer'
```

Use `--format json` to read the answer and its sources together:

```bash
terra docs ask --question "which providers support sleep data" --format json
```

```json
{
  "answer": "...",
  "confidence": "high",
  "sources": [
    {
      "label": "1",
      "title": "Setting up data sources",
      "description": "...",
      "url": "https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-sources",
      "type": "documentation",
      "breadcrumbs": ["Unified API", "Integration setup"]
    }
  ]
}
```

The response contains `answer`, `confidence`, and `sources`. Confidence is `high`, `medium`, `low`, or `unknown`. Each source has a URL; the other source fields may be absent.

An empty `sources` array means the answer was not grounded in the documentation. Check the sources before relying on an answer. A successful response with no sources still exits 0. Errors use the CLI's shared [exit codes](/developer-tools/terra-cli/output-and-scripting.md#exit-codes).

## For scripts and agents

Use `--select` to keep response fields, or `--jq` to extract a value:

```bash
terra docs ask --question "which providers support sleep data" --select answer,sources
terra docs ask --question "how do I verify a webhook signature?" --jq '.sources'
```

See [Coding agents](/developer-tools/terra-cli/coding-agents.md) for agent setup and command discovery.