# 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 the default LLM provider. Flag → `$ANTHROPIC_API_KEY` → `truto profiles set-key anthropic` → interactive prompt. | | **Fireworks API key** | Required only when you pick `--llm-provider fireworks`. Flag → `$FIREWORKS_API_KEY` → `truto profiles set-key fireworks` → interactive prompt. | | **Firecrawl API key** | Generic docs sites that need crawling, **and** `web_search` / `web_fetch` under the Fireworks provider. Flag → `$FIRECRAWL_API_KEY` → `truto profiles set-key firecrawl` → interactive prompt. | | **Truto login** | Required when improving an existing slug (`acme`) so the CLI can load live config and categories. | The CLI prompts for the LLM provider interactively when `--llm-provider` is omitted on a TTY (defaults to `anthropic` in CI / non-TTY). Pick **Fireworks AI** for Fireworks-hosted Kimi, DeepSeek, GLM, MiniMax, or Qwen models. ## 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 the LLM provider (Anthropic by default, or Fireworks via `--llm-provider fireworks`) and its API key. Resolve Firecrawl when crawling is needed (and for Fireworks `web_search` / `web_fetch`). - 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. ## LLM providers The build loop supports two LLM providers. Pick interactively when `--llm-provider` is omitted on a TTY; the default is `anthropic` in CI / non-TTY. | Provider | Flag | Models | Web tools | Notes | |----------|------|--------|-----------|-------| | **Anthropic** (default) | `--llm-provider anthropic` | Tiered Claude: `claude-opus-4-6` (agent), `claude-sonnet-4-6` (extraction/docs), `claude-haiku-4-5` (classification) | Anthropic **server-side** `web_search` / `web_fetch` | Adaptive thinking, `cache_control` blocks, container metadata | | **Fireworks AI** | `--llm-provider fireworks` | One shared **workhorse** model for agent + extraction, plus a cheap **classification** model | **Client-side** `web_search` / `web_fetch` via Firecrawl (requires `FIRECRAWL_API_KEY`) | No adaptive thinking, no Anthropic server tools, no `cache_control`; Fireworks prompt caching is automatic (CLI sends `x-session-affinity`) | ### Picking Fireworks ```bash # Interactive — the CLI prompts for the LLM provider when --llm-provider is omitted on a TTY truto integrations build https://docs.example.com acme # Non-interactive — pin Fireworks and a workhorse model export FIREWORKS_API_KEY=... truto integrations build https://docs.example.com acme \ --llm-provider fireworks \ --llm-model kimi-k2p7 ``` ### Fireworks model presets Fireworks uses a **shared workhorse model** for agent + extraction, plus a separate cheap **classification** model. Pin the workhorse with `--llm-model` (or the aliases `--llm-agent-model` / `--llm-extraction-model` — they set the same shared model). Override classification with `--llm-classification-model`. | Tier | Claude default | Fireworks default | Used for | |------|----------------|-------------------|----------| | Agent + extraction | Opus + Sonnet | `kimi-k2p7` (one model for both) | Discovery agent, build loop, docs, schemas | | Classification | `claude-haiku-4-5` | `deepseek-v4-flash` | Page classification, routing | **Workhorse presets** (pick one for agent + extraction): | Preset | Fireworks model | Notes | |--------|-----------------|-------| | `kimi-k2p7` | `accounts/fireworks/models/kimi-k2p7-code` | Coding specialist, MCP workflows (default) | | `glm-5p2` | `accounts/fireworks/models/glm-5p2` | 1M context flagship agent | | `minimax-m3` | `accounts/fireworks/models/minimax-m3` | K2.7-class agent, 512k context | | `qwen3p7-plus` | `accounts/fireworks/models/qwen3p7-plus` | Strong structured JSON for docs/schemas | | `deepseek-v4-pro` | `accounts/fireworks/models/deepseek-v4-pro` | 1M context reasoning | **Classification presets:** `deepseek-v4-flash` (default) or `gpt-oss-20b`. Raw `accounts/.../models/...` IDs also work on any tier flag. :::callout{type="warning"} Don't mix `--anthropic-model` with `--llm-provider fireworks` (or `--llm-model` with `--llm-provider anthropic`) — the CLI hard-errors. Use `--llm-model` (or `--llm-agent-model` / `--llm-extraction-model` / `--llm-classification-model`) for Fireworks, and `--anthropic-model` for Anthropic. ::: ### Embedding provider Hybrid source search (BM25 + cosine) defaults to a **local ONNX** model (`all-MiniLM-L6-v2`, ~35 MB, no API key). To use Fireworks-hosted embeddings instead: ```bash truto integrations build https://docs.example.com acme \ --embedding-provider fireworks \ --embedding-model qwen3-embedding-8b ``` `--embedding-provider fireworks` requires `FIREWORKS_API_KEY`. Supported `--embedding-model` presets: `local-minilm`, `qwen3-embedding-8b` (and aliases `qwen3`, `best`). The default for `--embedding-provider fireworks` is `qwen3-embedding-8b`. ### Web tools and Firecrawl `web_search` / `web_fetch` are always exposed to the agent, but the backend depends on the LLM provider: | | Anthropic (default) | Fireworks | |---|---------------------|-----------| | `web_search` / `web_fetch` | Anthropic server tools | Firecrawl-backed **client-side** tools | | Required keys | `ANTHROPIC_API_KEY` | `FIREWORKS_API_KEY` **and** `FIRECRAWL_API_KEY` | | Per-run budgets (build / discovery) | 10 search / 20 fetch | 10 search / 20 fetch | | OpenAPI spec hunt (`find_openapi_spec`) | 5 search / 5 fetch per invocation | 5 search / 5 fetch per invocation | Without a Firecrawl key, **Fireworks builds still run** but cannot use `web_search` or `web_fetch`. Doc crawling via `map_doc_site` / `scrape_pages` also requires Firecrawl. Use `--no-firecrawl` only when you accept a docs-only path without live web tools. ## 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. Also disables `web_search` / `web_fetch` under `--llm-provider fireworks` | | `--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-llm-cache` / `--refresh-llm-cache` apply to both LLM providers | | `--no-editor` | Skip opening the editor between Phase A and B | | `--editor ` | Editor command (`cursor`, `code`, …) | | `--llm-provider ` | `anthropic` (default) or `fireworks`. Prompts interactively when omitted on a TTY | | `--anthropic-api-key ` | Override Anthropic API key (flag → `$ANTHROPIC_API_KEY` → profile → prompt) | | `--anthropic-model ` | Override Claude model for all tasks (Anthropic provider only; tiered defaults: `claude-opus-4-6` / `claude-sonnet-4-6` / `claude-haiku-4-5`) | | `--fireworks-api-key ` | Override Fireworks API key (required for `--llm-provider fireworks`) | | `--llm-model ` | Pin Fireworks agent + extraction to one model. Presets: `kimi-k2p7`, `glm-5p2`, `minimax-m3`, `qwen3p7-plus`, `deepseek-v4-pro`, or a raw `accounts/.../models/...` ID | | `--llm-agent-model ` / `--llm-extraction-model ` | Aliases for `--llm-model` (agent and extraction share one model) | | `--llm-classification-model ` | Fireworks classification-tier model. Presets: `deepseek-v4-flash`, `gpt-oss-20b` | | `--embedding-provider ` | `local` (default, MiniLM ONNX) or `fireworks` (Qwen3, requires `FIREWORKS_API_KEY`) | | `--embedding-model ` | Embedding model preset: `local-minilm`, `qwen3-embedding-8b` (and aliases `qwen3`, `best`) | | `--no-embeddings` | Skip embedding the source index for this build (BM25-only search). Cached embeddings still survive for future runs | | `--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**, `--include-low-confidence`, `--plan-out`, `--report-out`, `-c`/`--category`, `-l`/`--label`, `--base-url`, `--no-bootstrap`, `--no-basic-details`, `--no-query-schema`, `--no-body-schema`, `--descriptions-only`, `--rewrite-bad-descriptions`, `--no-llm-canonicalize`, `--no-llm-regroup`, `--no-llm-split-buckets`, `--strict`, `--no-validate`, `--keep-inline-docs`) exit with an error (`2`) before any LLM key resolution or crawling runs, and point you at the new flow plus `truto integrations apply`. ## Bring-your-own keys | Key | Required when | | ------------------- | ---------------------------------------------- | | `ANTHROPIC_API_KEY` | Default build (`--llm-provider anthropic`) | | `FIREWORKS_API_KEY` | `--llm-provider fireworks` or `--embedding-provider fireworks` | | `FIRECRAWL_API_KEY` | Generic doc sites that need crawling, **and** `web_search` / `web_fetch` under `--llm-provider fireworks` | Resolution order for each: CLI flag → environment variable → `truto profiles set-key` → interactive prompt on a TTY. Keys are stored under the active profile, so `truto profiles use staging` and `truto profiles use prod` can hold different `anthropicApiKey` / `fireworksApiKey` / `firecrawlApiKey` values. > **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. To use Fireworks-hosted `qwen3-embedding-8b` embeddings instead, pass `--embedding-provider fireworks` (requires `FIREWORKS_API_KEY`). ## 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` | | LLM | `~/.truto/cache/anthropic/` (`%USERPROFILE%\.truto\cache\anthropic\` on Windows) | 7d | `--no-llm-cache`, `--refresh-llm-cache` | The LLM cache is keyed by (provider + model + system prompt + messages hash) and is **shared by both Anthropic and Fireworks** — Fireworks calls go through the same Anthropic-compatible adapter, so the on-disk path is the same despite the `anthropic/` directory name. Switching models or providers invalidates automatically. ## 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