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

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:

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

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.

Useful flags

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

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.

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