# AI-powered build

> Source: https://truto.one/docs/cli/integrations-build/

`truto integrations build` discovers API documentation, runs an **agentic** build, and writes a local **IntegrationFile** JSON (for example `acme.integration.json`). Nothing is pushed to Truto until you run [`truto integrations apply`](/docs/cli/integrations).

```bash
# Create a new integration from docs
truto integrations build https://docs.example.com/openapi.json

# Improve an existing integration (slug loads live config from your environment)
truto integrations build https://docs.example.com/openapi.json acme

# Push when you are satisfied
truto integrations apply acme.integration.json
```

You can pass **multiple source URLs** in any order; the CLI picks the highest-fidelity source as primary and indexes the rest. URLs must start with `http://`, `https://`, `file://`, `/`, or `./`. Any other positional argument is treated as the integration slug.

```bash
truto integrations build \
  https://docs.example.com/guides/rest-api/ \
  https://docs.example.com/static/openapi.json \
  acme
```

## Prerequisites

| Requirement | Notes |
| --- | --- |
| **Anthropic API key** | Required for all LLM work. Flag → `$ANTHROPIC_API_KEY` → `truto profiles set-key anthropic` → interactive prompt. |
| **Firecrawl API key** | Only when the source is a generic docs site that needs crawling (not raw OpenAPI / `llms-full.txt` / local files). |
| **OpenAI API key** | Optional. Embeds the crawled doc index for hybrid search; omit with `--no-embeddings` for BM25-only. |
| **Truto login** | Required when improving an existing slug (`acme`) so the CLI can load live config and categories. |

## What happens during a build

The default flow (no flags) is **agentic**. An older **12-section orchestrator** still exists behind `--legacy-flow` for parity testing; it is not what new users should follow.

### 1. Pre-flight

- Resolve Anthropic (and Firecrawl / OpenAI when needed) keys.
- Optional prompt: **general build instructions** (press Enter to skip). Skip non-interactively with `--instructions "…"`.
- Load the pattern catalog and exemplars used by audit and the agent.

### 2. Discovery

The CLI extracts and indexes your source(s): OpenAPI, Postman collections, GraphQL, `llms-full.txt`, Mintlify/Readme tricks, Firecrawl crawl, and related tiers. Pin behavior with `--source-tier` when auto-detection picks the wrong tier.

### 3. Audit (informational)

The CLI compares discovered docs, live config (on update), and catalog patterns, then prints **audit findings** to stderr (severity, section, resource/method, message). On the agentic path these are **not** a menu you must complete — the agent uses them as context. On `--legacy-flow`, findings drive a multiselect of which sections to build.

### 4. Phase A — autonomous build

The agent works through the integration file in a **working copy** next to your output path (for example `.acme.integration.json.working`). It calls tools (read source docs, search the index, read corpus examples, validate patches) and applies **cascade patches** without per-section yes/no prompts.

Phase A ends when the agent signals completion or hits its turn budget (you can still refine in Phase B).

### 5. Editor (optional)

Unless you pass `--no-editor`, the CLI opens the working file in your editor (`$VISUAL` / `$EDITOR`, `--editor`, or profile). Fix anything by hand before refinement.

### 6. Phase B — refinement loop

You drive changes with **free-form instructions**:

```text
Refinement instruction (e.g. "website_id should be a credential, not a query param" — leave empty to finish):
```

For each instruction the agent proposes a patch. You review the diff and choose:

| Choice | Meaning |
| --- | --- |
| **[a] accept and continue** | Apply the patch to the working file |
| **[s] skip this section** | Decline this patch |
| **[c] chat (refine via feedback)** | Explain what to change; the agent re-proposes |

Press **Enter** on an empty line to finish Phase B. Type **`:edit`** to open the working file in your editor again (with validate / discard).

Accepted refinements can be saved as **learnings** for future builds (`~/.truto/build-learnings.jsonl`).

### 7. Documentation generation

After Phase B, the CLI generates **per-method documentation rows** in the background (`description`, `query_schema`, `body_schema`, `response_schema`) from the final config and source index. This runs automatically; you do not step through 12 sections manually.

### 8. Output

The final file is written to `--out` or `<slug>.integration.json`, with a reminder to run `truto integrations apply`.

:::callout{type="info"}
**Resume:** If a working file already exists with substantial content, Phase A is skipped and you go straight to Phase B refinement.
:::

## Integration file shape

The output follows the **IntegrationFile** schema: `name`, `config` (auth, pagination, `resources`, webhooks, etc.), optional `documentation` rows, `audit_notes`, and `_refinements` from Phase B. The agent still reasons about the same conceptual areas (basic details, base URL, auth, resources, webhooks, …) but as patches on one JSON document, not a fixed **[a]/[b]/[c]** menu per section.

## Useful flags

| Flag | Purpose |
| --- | --- |
| `--out <file>` | Output path (default `<slug>.integration.json`) |
| `--instructions <text>` | Skip the build-instructions prompt |
| `--source-tier <tier>` | Pin doc extraction (`auto`, `openapi-only`, `postman`, `llms-full`, `graphql-introspection`, … — run `truto integrations build --help` for the full list) |
| `--no-firecrawl` | Skip Firecrawl; use cheaper extraction only |
| `--refresh-firecrawl-cache` / `--no-llm-cache` / `--refresh-llm-cache` | Control local caches under `~/.truto/cache/` |
| `--no-editor` | Skip opening the editor between Phase A and B |
| `--editor <cmd>` | Editor command (`cursor`, `code`, …) |
| `--anthropic-model <model>` | Override model for all LLM tasks |
| `--legacy-flow` | Use the old 12-section orchestrator (`[a]` Accept, `[s]` Skip, `[w]` Seems wrong per section) |
| `--docs-only <file-or-slug>` | Skip build; regenerate documentation rows only |
| `--resource <names>` | With `--docs-only`, limit which resources get new doc rows |
| `--debug-log <path>` / `--no-debug-log` | JSONL transcript of the build (default on under `~/.truto/logs/`) |

Deprecated flags from older builds (for example `--resources`, `--yes`, `--dry-run` on **build**) exit with an error and point you at the new flow plus `truto integrations apply`.

## Bring-your-own keys

| Key | Required when |
| --- | --- |
| `ANTHROPIC_API_KEY` | Always |
| `FIRECRAWL_API_KEY` | Generic doc sites that need crawling |
| `OPENAI_API_KEY` | Optional embeddings (unless `--no-embeddings`) |

Resolution order for each: CLI flag → environment variable → `truto profiles set-key` → interactive prompt on a TTY.

## Doc-discovery and caches

The discovery pipeline tries cheap sources before Firecrawl (OpenAPI direct, `llms.txt` / `llms-full.txt`, markdown siblings, then scoped Firecrawl). See `truto integrations build --help` for `--source-tier` values.

| Cache | Location | TTL | Bypass |
| --- | --- | --- | --- |
| Firecrawl | `~/.truto/cache/firecrawl/` | 24h | `--refresh-firecrawl-cache` |
| Anthropic | `~/.truto/cache/anthropic/` | 7d | `--no-llm-cache`, `--refresh-llm-cache` |

## After the build

Push the file with [Managing integrations — Apply](/docs/cli/integrations#apply). Validate structure first with [Lint](/docs/cli/integrations#lint).

To add a **single** method when you already know the HTTP verb and path (no LLM), use [Add method](/docs/cli/integrations-add-method) instead of a full build.

## Next steps

- [Managing integrations](/docs/cli/integrations) — CRUD, `init`, `validate`, `apply`, `lint`
- [Add method](/docs/cli/integrations-add-method) — mechanical one-method PATCH
- [Examples](/docs/cli/examples) — end-to-end workflows