AI-powered build

truto integrations build reads an API's docs and writes an integration file you can review.

Nothing reaches Truto until you run truto integrations apply.

flowchart LR
    docs["API docs or spec"] --> build["build"]
    build --> asked{"Questions?"}
    asked -->|"yes"| answer["build --continue"]
    answer --> review["Review the file"]
    asked -->|"no"| review
    review --> apply["apply"]

Quick start

# 1. Build from the API's docs or OpenAPI spec
truto integrations build https://docs.example.com/openapi.json
 
# 2. Answer anything the build asked (it prints this command for you)
truto integrations build --continue acme.integration.json --answer q1="…"
 
# 3. Push it to Truto
truto integrations apply acme.integration.json

Before you start

You need:

• An LLM key
  • Anthropic (the default): ANTHROPIC_API_KEY
  • Fireworks, only with --llm-provider fireworks: FIREWORKS_API_KEY
• A Firecrawl key (FIRECRAWL_API_KEY), only for docs sites that need crawling
• A Truto login, only to update an existing integration

No key set? In a terminal the CLI asks for it and offers to save it to your profile. You can also save one ahead of time with truto profiles set-key anthropic (or fireworks, firecrawl).

How a build works

1. Reads your sources. OpenAPI, Postman, GraphQL, llms-full.txt, or a crawl of the docs site.
   • Pass several URLs, in any order. The CLI uses the best one first.
2. Builds the file. An AI agent writes the config and checks each change as it goes.
3. Lets you fix things. It opens the file in your editor, then takes plain-English fixes such as "website_id should be a credential".
   • Press Enter on an empty line when you're done.
   • Skip the editor with --no-editor.
4. Writes the docs. Every method gets its own documentation rows.
5. Saves the result:
   • acme.integration.json: the integration
   • acme.integration.report.md: a report you can read (plus .report.json for tools)
   • acme.integration.json.committed: the copy apply compares against

When the build asks a question

The build stops and asks instead of guessing. The method waits, the question is saved, and the rest of the build carries on.

It asks when, for example:

• a value such as {{subdomain}} is used, but nothing fills it
• a list endpoint doesn't show where its rows are
• a method has no documentation
• users type in an API key, but nothing checks the key when they connect

Answer it

• In a terminal: the build asks at the end. Press Enter to skip a question.
• From a script or an agent: answer later.

truto integrations build --continue acme.integration.json --answer q1="…"
truto integrations build --continue acme.integration.json --answers answers.json

--continue rebuilds only the methods that were waiting. Everything else stays exactly as it was.

Edited the file by hand? Run truto integrations build --recheck acme.integration.json before --continue.

Results and exit codes

Every build ends with a summary: the status, the counts, any open questions, and the next command to run.

• --fail-on sets what counts as a failure: blocking (default), errors, incomplete or none.
• In CI, exit 3 means waiting, not broken. If your runner fails on any non-zero exit, pass --fail-on none.
• Scripts and agents should pass -o json: one JSON summary and no prompts.

The report

acme.integration.report.md shows, for each method:

• where its docs came from
• what the agent assumed
• which checks ran
• a confidence of low, medium or high

Start with the low ones. Confidence never blocks anything.

Run without prompts

truto integrations build https://docs.example.com/openapi.json acme \
  --instructions "Contacts, companies and deals only" \
  --refine "website_id should be a credential, not a query param" \
  --auto-accept-patches --no-editor -o json

Update an existing integration

• Rebuild on top of what's live: pass the slug after the docs URL.
• Only add what's missing: --only-missing adds the methods that are in the docs but not live.
  • Existing methods, auth and pagination stay as they are.
• Only refresh the docs: --docs-only <file-or-slug> regenerates documentation rows.
  • It writes <slug>.docs.integration.json. Push that file with truto integrations apply <file> --docs-only.

LLM providers

• In a terminal, the CLI asks which provider to use. In CI it uses Anthropic.
• Don't mix them. --anthropic-model with Fireworks, or --llm-model with Anthropic, is an error.

Useful flags

See every flag: truto integrations build --help

Older flags such as --yes, --dry-run and --strict are gone. They exit with code 2 and name the command to use instead.

Next

• Push the file with Apply.
• To add one method without AI, use Add method.