AI-powered 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.

# 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.

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

Prerequisites

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 <url> (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:

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:

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 <slug>.integration.json, with a reminder to run truto integrations apply.

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.

Picking Fireworks

# 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.

Workhorse presets (pick one for agent + extraction):

Classification presets: deepseek-v4-flash (default) or gpt-oss-20b. Raw accounts/.../models/... IDs also work on any tier flag.

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:

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:

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

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

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.

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. Validate structure first with Lint.

To add a single method when you already know the HTTP verb and path (no LLM), use Add method instead of a full build.

Next steps

• Managing integrations — CRUD, init, validate, apply, lint
• Add method — mechanical one-method PATCH
• Examples — end-to-end workflows