CLI: Integrations and Broker

Two families cover external systems: integration is setup (connect, confirm, disconnect), and broker is execution (operate an already-connected provider). They are deliberately separate. See Integrations and Connections for the model and Broker for the semantics. Add --json to any command for machine output.

Integrations (setup)

Command	Description
`integration catalog`	Providers you can connect.
`integration connect <provider>`	Start the authorize flow.
`integration confirm <provider>`	Persist the connection after authorizing.
`integration list`	Your connected integrations.
`integration rm <id>`	Disconnect (aliases: `delete`, `disconnect`); revokes the credential.

driftless integration catalog
driftless integration connect notion
driftless integration confirm notion
driftless integration list

Broker (operate)

The broker is gated (off by default in production) and fail-closed. driftless broker setup prints guidance only.

Command	Description
`broker connections`	Your connections with health, status, and criterion.
`broker operations [provider]`	List operations, or search with `--query`, `--provider`, `--effect read\|write`, `--risk low\|medium\|high`, `--limit`, `--cursor`, `--refresh`.
`broker capabilities <provider>`	The capability directory.
`broker inspect <provider> <op>`	One operation’s full spec.
`broker invoke <provider> <op> [--input <json>\|@file] [--idempotency-key <k>]`	Execute one operation inline; the key makes a write retry replay, never re-execute.
`broker criterion <provider> [--add <slug>\|--rm <slug>]`	Bare: the connection’s EFFECTIVE context (criterion resolved to trust/staleness — read it before working the provider). With flags: attach or detach a topic slug.

driftless broker connections
driftless broker operations notion
driftless broker invoke notion <operation> --input @payload.json

Reading and materializing

Command	Description
`broker models <provider>`	Importable record models (enabled syncs).
`broker records <provider> --model <m>`	Read a model’s records from the mirror (`--modified-after`, `--cursor`, `--limit`).
`broker document <provider> <externalId>`	Read one document’s bounded, live, citeable content from any content provider (`--max-bytes`).
`broker page <pageId>`	DEPRECATED Notion-only alias of `broker document notion <id>`.
`broker index <provider>`	Materialize connector documents. `--dry-run` previews; also `--model`, `--limit`, `--sample-limit`, `--max-bytes`, `--import-run-id`.
`broker import <provider> --collection <id>`	Import mirror records into a Collection via its saved connector mapping (`--model`, `--modified-after`, `--max-pages`).
`broker events [provider]`	The inbound provider event feed (`--limit`).

records reads a cache; document reads live; index writes Driftless-owned connector documents (never the provider); import writes Collection Records. Normal context retrieve never queries a provider. A record deleted at the provider tombstones its connector document on the next index run (it stops being citable); a disconnect soft-deletes all of the provider’s documents.

Gates and grants

A broker call can be refused by any of three gates: the master flag, the external-lane rollout, and per-principal grants. For a CLI call authenticated with your own key you are an internal caller (governed by identity and scopes, not grants); a faceless OAuth/MCP caller additionally needs rollout on and a matching grant. Managing grants is owner/admin only, via the API or dashboard.

Flags, files, and JSON

@file is accepted by broker invoke --input.
--json works on every command.
broker invoke on a write effect requires an idempotency_key to be safely replayable; writes are never auto-retried.

Integrations and Connections - the setup-to-usable chain and provider availability.
Broker - actions, gates, and read/write semantics.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

CLI: Integrations and Broker

Integrations (setup)

Broker (operate)

Reading and materializing

Gates and grants

Flags, files, and JSON

​Integrations (setup)

​Broker (operate)

​Reading and materializing

​Gates and grants

​Flags, files, and JSON

​Related

Integrations (setup)

Broker (operate)

Reading and materializing

Gates and grants

Flags, files, and JSON

Related