Managing integrations | Truto Documentation

Integration definitions are third-party app connectors in Truto. The CLI exposes full CRUD plus helpers to scaffold, validate, and inspect integrations.

Quick reference

truto integrations list
truto integrations get <id> -o json
truto integrations create -b '{"name":"my-app","config":{"label":"My App","base_url":"https://api.example.com"}}'
truto integrations update <id> -b '{"category":"crm"}' --lock-version 1
truto integrations delete <id> -f

Scaffold a new integration (`init`)

Interactively create a starter config and POST it to Truto:

truto integrations init acme-crm
truto integrations init --label "Acme CRM" --auth oauth2 --base-url https://api.acme.com
truto integrations init acme-crm --print          # print config only, no API call
truto integrations init acme-crm --out acme.json  # write to file

Validate config (`validate`)

Validate against the IntegrationConfig schema before pushing:

truto integrations validate <integration-id>
truto integrations validate -f ./config.json
cat config.json | truto integrations validate --stdin

Discovery helpers

# Tools/methods exposed by an integration
truto integrations tools <id-or-name>
 
# Unified APIs mapped to an integration
truto integrations unified-apis <id-or-name>

CRUD details

List filter: --name

Create fields: name (required), config (JSON, required), category

Update fields: category, config (JSON), --lock-version (required — optimistic locking; the record's current version from get, or "version" in -b)

The server replaces the whole stored config on update. Before sending, the CLI compares your config with the live one and refuses an update that would drop top-level keys, resources, or methods. Choose how to send a partial or shrinking config:

Flag	Effect
`--merge-config`	Merge your partial `config` over the live one (top-level keys replaced whole, `resources` merged per resource) and send the result
`--replace-config`	Send `config` as given, replacing the stored config — needed to remove keys, resources, or methods on purpose
`--dry-run`	Print the plan and the config key diff; send nothing

truto integrations get <id> --at-version <n> reads a stored older version of the record.

# Create interactively
truto integrations create
 
# Pipe from stdin
echo '{"name":"test","config":{"label":"Test"}}' | truto integrations create --stdin

Apply

Push an IntegrationFile JSON (typically from integrations build) to your Truto environment. Non-interactive — no LLM calls.

truto integrations apply acme.integration.json
truto integrations apply acme.integration.json --dry-run        # validate + show plan only
truto integrations apply acme.integration.json --docs-only      # push documentation rows only (integration must exist)
truto integrations apply acme.integration.json --slug-override renamed-slug  # override slug on CREATE

Validates the file against the IntegrationFile schema before any API call.
Creates or updates the integration from the file's id / name.
Diffs and syncs per-method documentation rows and integration-wide doc types.
Prints a summary of created, updated, and unchanged resources.

Lint

Static audit of integration config — no LLM, no network beyond an optional slug lookup:

truto integrations lint ./acme.integration.json
truto integrations lint acme-crm    # audit live integration by slug
truto integrations lint ./acme.integration.json --ignore-warnings
truto integrations lint acme-crm --integration-config-dir ./corpus

Exit codes: 0 clean, 1 warn- or error-level findings remain, 2 input error. Info-level findings never change the exit code. --ignore-warnings lowers the exit-1 bar to error-level findings only; --ignore-info hides info-level findings from the table output (-o json, yaml, ndjson, and csv always include every finding).

Command	Purpose
`integrations build`	Agentic build from API docs → local JSON file
`integrations add-method`	Add one method when you supply HTTP details (no LLM)