# Managing integrations

> Source: https://truto.one/docs/cli/integrations/

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

## Quick reference

```bash
truto integrations list
truto integrations get <id> -o json
truto integrations create -b '{"name":"my-app","config":{"label":"My App","auth_type":"oauth2"}}'
truto integrations update <id> -b '{"category":"crm","version":1}'
truto integrations delete <id> -f
```

## Scaffold a new integration (`init`)

Interactively create a starter config and POST it to Truto:

```bash
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:

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

## Discovery helpers

```bash
# 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), `version` (required — optimistic locking; fetch with `get` first)

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

```bash
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)
```

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

```bash
truto integrations lint ./acme.integration.json
truto integrations lint acme-crm    # audit live integration by slug
```

Exit codes: `0` clean, `1` findings remain, `2` input error.

## Related commands

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

## Categories

List integration categories (verticals such as `crm`, `ats`, `helpdesk`):

```bash
truto categories list
truto categories list --name crm
```