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 ask answers a question from Terra's published documentation and cites the pages the answer came from. Use it to check an endpoint, a payload field, or a setup step without leaving the terminal.

terra ask "how do I generate an auth widget"

The answer prints first. A SOURCES list follows, with the title and URL of each page it came from.

It also gives a coding agent the documentation as a command. An agent with the CLI installed can look things up with terra ask and needs no separate documentation server. See Coding agents.

terra ask needs an authenticated CLI. Run terra login first, or set TERRA_ADMIN_TOKEN. See Authentication.

Ask a question

The question is one argument, so quote it. Unquoted, the shell splits it into several arguments, eats the apostrophe in "what's", expands the question mark, and reads a word starting with a dash as a flag.

terra ask "how do I verify a webhook signature?"
terra ask "what does --dry-run do?"
terra ask "which providers support sleep data"

A question that starts with a dash goes after --, which stops flag parsing:

terra ask -- "--paginate stops after ten pages, how do I raise it?"

Your question is sent to Terra, which answers it from the documentation. The CLI's own telemetry never carries it, because positional arguments are never collected.

Read the sources

The search answers whatever it is asked, and rates itself confident while doing so. An answer that cites no sources did not come from the documentation. The answer still prints, with a note on stderr:

That answer cites no documentation, so treat it with care.

So sources is the signal that an answer came from the documentation, and confidence is not. When the search does report low confidence, the CLI says so on stderr and asks you to check the sources.

For scripts and agents

--format json prints a stable schema. Every field is always present: sources is an empty array rather than absent when nothing was found, and confidence is one of high, medium, low, or unknown.

terra ask "which providers support sleep data" --format json

{
  "question": "which providers support sleep data",
  "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"]
    }
  ]
}

Unlike the rest of the CLI, the prose output does not become JSON when piped, so an answer read in a pager stays readable. Pass --format json explicitly when a script consumes it.

Exit codes

Code	Meaning
0	Answered, including when nothing was found
1	The API returned an error
2	Not authenticated
3	The question was rejected before it was searched
4	The question was missing, or was not quoted into one argument

Finding nothing is not a failure of the CLI or the API, so it exits 0. Check sources rather than the exit code to tell whether an answer came from the documentation.