# 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#apply). ```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). | | **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 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. By default the CLI uses **agentic discovery**; pass `--legacy-discovery` to force the older deterministic tier ladder (GraphQL sources always use legacy discovery). For OpenAPI or GraphQL specs, the CLI can also crawl companion human-readable doc pages unless you pass `--no-companion-docs`. Pass explicit roots with `--companion-docs ` (repeatable). ### 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`; Windows: `%USERPROFILE%\.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 `.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. **Only missing methods:** On an existing integration slug, pass `--only-missing` to add API methods that appear in the source but are not yet on the live integration — without changing existing methods, auth, or pagination. Incompatible with `--legacy-flow` and `--docs-only`. Phase B refinement is skipped in this mode. ::: ## 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 ` | Output path (default `.integration.json`) | | `--instructions ` | Skip the build-instructions prompt | | `--source-tier ` | Pin doc extraction (`auto`, `openapi-only`, `postman`, `llms-full`, `graphql-introspection`, … — run `truto integrations build --help` for the full list) | | `--legacy-discovery` | Force legacy deterministic discovery instead of the agentic loop (default) | | `--no-spec-web-search` | Skip web search when hunting for an OpenAPI spec URL | | `--companion-docs ` / `--no-companion-docs` | Crawl extra doc-site roots alongside OpenAPI/GraphQL (`--companion-docs` is repeatable) | | `--max-pages ` | Cap doc pages walked during discovery (default `200`) | | `--only-missing` | UPDATE mode: add missing methods only; requires existing integration slug | | `--integration-config-dir ` | Local integration corpus for pattern matching (`$TRUTO_INTEGRATION_CONFIG_DIR` or profile `integrationConfigDir`) | | `--no-firecrawl` | Skip Firecrawl; use cheaper extraction only | | `--firecrawl-ignore-robots-txt` | Pass `ignoreRobotsTxt: true` to Firecrawl (enterprise plans only) | | `--refresh-firecrawl-cache` / `--no-llm-cache` / `--refresh-llm-cache` | Control local caches under `~/.truto/cache/` (Windows: `%USERPROFILE%\.truto\cache\`) | | `--no-editor` | Skip opening the editor between Phase A and B | | `--editor ` | Editor command (`cursor`, `code`, …) | | `--anthropic-api-key ` | Override Anthropic API key (flag → `$ANTHROPIC_API_KEY` → profile → prompt) | | `--firecrawl-api-key ` | Override Firecrawl API key (flag → `$FIRECRAWL_API_KEY` → profile → prompt) | | `--anthropic-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 ` | Skip build; regenerate documentation rows only | | `--resource ` | With `--docs-only`, limit which resources get new doc rows | | `--debug-log ` / `--no-debug-log` | JSONL transcript of the build (default on under `~/.truto/logs/`; Windows: `%USERPROFILE%\.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 | Resolution order for each: CLI flag → environment variable → `truto profiles set-key` → interactive prompt on a TTY. > **Note:** Hybrid search (BM25 + cosine) is now powered by a local ONNX model (`all-MiniLM-L6-v2`) downloaded automatically on first use (~35 MB). No external API key is required. ## 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/` (`%USERPROFILE%\.truto\cache\firecrawl\` on Windows) | 24h | `--refresh-firecrawl-cache` | | Anthropic | `~/.truto/cache/anthropic/` (`%USERPROFILE%\.truto\cache\anthropic\` on Windows) | 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