Skip to content

truto unified-mappings build reads an integration's proxy API and writes the JSONata mapping rows connecting it to a unified model (crm, ats, hris). It saves the result as a local MappingFile, for example acme.crm.mappings.json.

Nothing reaches Truto until you run truto unified-mappings apply.

This is the mapping-side companion to truto integrations build. Build the integration first, so it has proxy resources. Then map it to a unified model.

How a build works
flowchart LR
    source["Account or docs"] --> build["build"]
    build --> asked{"Questions?"}
    asked -->|"yes"| answer["build --continue"]
    answer --> validate["validate"]
    asked -->|"no"| validate
    validate --> apply["apply"]

Quick start

# 1. Build mappings for an integration against a unified model
truto unified-mappings build acme crm --account <id>
 
# 2. Answer anything the build asked (it prints this command for you)
truto unified-mappings build --continue acme.crm.mappings.json --answer q1="…"
 
# 3. Check the file without pushing
truto unified-mappings validate acme.crm.mappings.json
 
# 4. Push it to Truto
truto unified-mappings apply acme.crm.mappings.json --target base

No account yet? Build straight from docs instead:

truto unified-mappings build acme crm \
  --source-url https://docs.acme.com/openapi.json --yes
Tip

Already marked a test account for this integration? Skip --account: truto profiles set test-account.<integration> <id> is used automatically. The profile's default integrated account is never sampled.

Before you start

You need:

  • A built integration with proxy resources. Build it first if it doesn't exist yet.
  • A Truto login, so the build can read the integration config, the unified model schema, and any existing mapping rows.
  • Live samples or docs: pass --account <id> (or mark a test account), at least one --source-url, or both. Without either, the build exits with an error.
  • 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

No key set? In a terminal the CLI asks for it and offers to save it to your profile. Resolution order: flag, environment variable, truto profiles set-key, then an interactive prompt.

Want a different model? Override it with --anthropic-model (Anthropic) or --llm-model (Fireworks).

Building from docs? Searching them needs no key. A small local model (~35 MB) downloads on first use.

How a build works

The build is agentic: the model routes each unified resource/method (a "cell," for example contacts.list) to a proxy endpoint. It samples the endpoint, writes the JSONata, and validates it. --structured swaps in a fixed per-cell pipeline instead, for cheaper or parity runs.

  1. Routes each cell to the proxy endpoint that serves it. This includes cross-name routes (unified accounts to proxy companies) and conditional, when-guarded routes.
  2. Grounds it in a sample, in order:
    • a live proxy call, when --account or a marked test account is set
    • a documented example already on the integration
    • your --source-url docs
    • After a recent config change, the first live sample waits (about 7 minutes) for the cache to refresh. Later samples don't wait.
    • A read cell with no sample waits on a question instead of guessing. Write cells (create/update/delete) build from the documented request body even with no response example.
  3. Generates and checks the JSONata. Validates each field against the sample and the unified schema. Rejects expressions copied verbatim from another integration.
  4. Refines interactively. In a terminal, type a plain-English fix, such as "strip the trailing Z from start times", and the agent rebuilds that cell.
    • Type :show to print the full review.
    • Press Enter on an empty line to finish.
    • Skipped with --no-refine, --yes, --only-missing, or when output is piped.
  5. Saves the result:
    • acme.crm.mappings.json: the MappingFile (integration and model identifiers, a write_target of base or env, and the generated cells[])
    • acme.crm.mappings.report.md: a report you can read
    • a .committed copy beside it, that apply compares against

Rerunning a build? It resumes from the existing file: built cells are kept, failed ones retried. Pass --fresh to start over, or --only-missing to add only the cells you're missing.

When the build asks a question

A cell waits instead of shipping a guess when, for example:

  • a read cell has no sample: no live call, no documented example, no docs hit
  • the router can't tell which proxy method serves the cell
  • a required field or a value list's source is unclear

Answer it

  • In a terminal: the build asks at the end of the run, before the refinement loop.
  • From a script or an agent: answer later.
truto unified-mappings build --continue acme.crm.mappings.json --answer q1="…"
truto unified-mappings build --continue acme.crm.mappings.json --answers answers.json

--continue rebuilds only the cells your answers name. Every other cell stays exactly as committed.

  • Naming a proxy method? Answer with resource.method, for example people.list.
  • No sample to give? Point it at one: --account <id> or a --source-url with an example. Or confirm the mapping as already built.

Edited the file by hand? Run truto unified-mappings build --recheck acme.crm.mappings.json first.

Danger

Never paste a key, token or password as an answer. Say where the value comes from instead, for example <value from the previous response>. An answer that looks like a credential is refused.

Results and exit codes

Every build ends with a summary: status, counts, open questions, and the next command to run. The same summary is saved in the file, with a Markdown report beside it (for example acme.crm.mappings.report.md).

Exit Meaning
0 Nothing waits or is blocked.
3 A cell waits for an answer or is blocked, or there's a conflict over the file or its target.
1 A cell failed with an error and waits on no question, or the build itself failed.
  • This build has no --fail-on flag. Exit 3 means waiting or blocked, not broken.
  • Scripts and agents should pass -o json: one JSON summary and no prompts, printed once at the end.
  • build_summary.status is complete, partial (built, with recorded gaps), or incomplete (cut short).
  • skipped cells say why no mapping was made. warnings flag ones worth a second look, for example a hardcoded custom_fields.
Info

Changed from 1.0.38: a routed cell the build could not produce used to exit 0. It now exits 3, with other waiting or blocked cells.

Validate

Check a MappingFile without pushing anything. It's deterministic: no LLM calls, no writes.

truto unified-mappings validate acme.crm.mappings.json
truto unified-mappings validate acme.crm.mappings.json -v   # list every warning
  • Checks each cell against the target config and schema.
  • Only an observed sample or a documented example backs a check. Anything else is unverified, not passed.
  • Passing locally isn't backend parity: the CLI and worker engines differ.
  • Exits non-zero on errors. Warnings never fail it.
  • Pass --environment-id to check against an env schema override.

Apply

Push a MappingFile to Truto. Apply rechecks every cell, reconciles it against its baseline and live state, and writes only what it validates.

truto unified-mappings apply acme.crm.mappings.json --target base
truto unified-mappings apply acme.crm.mappings.json --dry-run   # offline preview, no live comparison
  • --target base writes team-owned rows. --target env writes per-environment overrides and needs a file built with --environment-id.
  • --resolve '<cell>=mine|theirs' settles a reported clash: --resolve '<cell>=mine' keeps your draft, --resolve '<cell>=theirs' takes the live row.
  • --test-account <id> (or a marked test account) lets apply run eligible read tests against the live account. It never runs provider mutations.
  • --yes skips the confirmation, not validation.
  • Every write is reread, so a stale or partial run stays recoverable.
Warning

Without a terminal (a script, an agent, CI, or -o json), apply writes nothing and exits 3, unless you pass --yes. The safer path: run --prepare, then --plan <path>.plan.json --expect-digest <digest> once the plan is approved.

Useful flags

Flag What it does
-a, --account <id> Integrated account for live proxy samples
--source-url <url|path> Docs URL or local file. Repeatable, comma-separated, or a glob
--resources <list> / --methods <list> Build only these unified resources or methods
--only-missing Build only cells absent from the existing file
--fresh Ignore the existing file and start over
--environment-id <id> Resolve schema overrides and target env rows
--out <file> Output path (default <integration>.<model>.mappings.json)
--no-refine Skip the interactive refinement loop
--yes Non-interactive: skip account/docs prompts

See every flag: truto unified-mappings build --help

Next