Docyrus Integrations & Connectors

Use third-party integrations from the terminal with docyrus connect. A connector (a.k.a. data provider) is a platform-defined external integration (identified by a slug, e.g. msgraph, twilio, meta) that bundles managed auth + a set of callable actions + data sources. You discover connectors and their actions, then run actions or make raw authenticated requests through the connector's provider auth — without handling tokens yourself.

Concepts (read first)

Connector / data provider — the integration definition (core_data_provider), addressed by slug. Holds the auth type, base URL, and the actions it exposes.
Action — a callable operation a connector exposes (core_action), addressed by provider slug + action key (e.g. msgraph + sendEmailWithOutlook). Has inputJsonSchema / outputJsonSchema.
Connection — a tenant's stored credentials for a connector (tenant_connection), or a per-user OAuth2 connection (tenant_connection_user). Connections hold the tokens/keys.
Connection account — an optional sub-account within a connection (e.g. one of several ad accounts / mailboxes), addressed by --connectionAccountId. List the available ones (and their ids) with GET /v1/connectors/{slug}/connection-accounts — see Listing connection accounts.

⚠️ Connections are NOT created by this CLI. There is no create-connection command. Credentials/OAuth connections are set up in the Docyrus UI (OAuth flow) or via the raw API. This skill discovers and uses connectors; if no connection exists for a provider, the user must connect it first.

Workflow

Confirm auth. Every command needs an active session.

docyrus auth who --json        # or: docyrus auth login

Discover the connector you need and its slug:

docyrus connect list-connectors --q "twilio" --json
docyrus connect get-connector twilio --json    # → its actions[] and dataSources[]

Confirm a connection exists for that provider (you need credentials to actually run):
```
docyrus connect list-connections twilio --json
# → { tenantScope: [{id,name,...}], userScope: { connected, connectionId } }
```
If tenantScope is empty and userScope.connected is false, stop and ask the user to connect the provider in the Docyrus UI first.
List the connection's accounts when the provider has sub-accounts (mailboxes, ad accounts, WhatsApp numbers) — this is where a connectionAccountId comes from:
```
docyrus curl "/v1/connectors/meta/connection-accounts" --format json
# → { data: [{ id, accountId, accountName, connectionId, userConnectionId, data, createdOn }], meta: {...} }
```
An empty list is normal: accounts only exist after the tenant-accounts fetch has run for that connection.

Inspect the action's input schema before calling:

docyrus connect get-action twilio sendSms --json    # → inputJsonSchema / outputJsonSchema / requestMethod

Run the action (build --params to match the input schema). Dry-run first to preview:

docyrus connect run-action twilio sendSms -p '{"to":"+1555...","body":"Hi"}' --dryRun --json
docyrus connect run-action twilio sendSms -p '{"to":"+1555...","body":"Hi"}' --json

Or make a raw authenticated request when there's no action for what you need:

docyrus connect curl msgraph "/me/messages" -X GET --json

A full reference of every command, the data model, auth types, connection resolution, and gotchas is in references/connector-model-and-actions.md.

Command cheat-sheet

All commands need an active session; append --json. Connectors are addressed by slug, actions by slug + actionKey.

docyrus connect list-connectors [--q <kw>] [--limit 100] [--offset 0]   # find connectors
docyrus connect get-connector  <slug>                                    # detail: actions[] + dataSources[]
docyrus connect list-connections <slug>                                  # tenantScope[] + userScope{connected,connectionId}
docyrus connect get-action     <slug> <actionKey>                        # input/output JSON schemas + requestMethod
docyrus connect run-action     <slug> <actionKey> -p '<json>' [-c <connId>] [--connectionAccountId <id>] [-n]
docyrus connect curl           <slug> <endpoint> [-X <method>] [-d '<json>'] [--headers '<json>'] [-c <connId>] [--connectionAccountId <id>]

run-action: -p/--params is a JSON object matching the action's inputJsonSchema (server-validated — AJV, 400 on mismatch). -n/--dryRun previews the request client-side without sending. Connection selectors (-c/--connectionId, --connectionAccountId) are sent as headers.
curl: <endpoint> is a relative path (appended to the connection/provider base URL) or an absolute http… URL (used verbatim). -X sets the HTTP method (default GET); -d/--headers are JSON. The provider auth header is injected automatically.

Listing connection accounts

Sub-accounts live on the Docyrus API, not on the connect group — there is no connect list-connection-accounts subcommand. Reach the endpoint with the top-level docyrus curl (Docyrus API paths, not provider paths):

docyrus curl "/v1/connectors/{slug}/connection-accounts" --format json
docyrus curl "/v1/connectors/msgraph/connection-accounts?connectionId=<uuid>&q=sales&limit=50" --format json

Query params: connectionId (uuid — matches a tenant or user connection), q (matches account name or provider account id), limit (100), offset (0). Response is { data: [...], meta: { total, limit, offset } }; unknown slug → 404.

Field	Meaning
`id`	The value to pass as `--connectionAccountId` (header `x-connection-account-id`, or `connectionAccountId` in a `connect curl` body).
`accountId` / `accountName`	The account's id and display name at the provider — not Docyrus ids.
`connectionId` / `userConnectionId`	Which connection the account came through; exactly one is set.
`data`	The provider payload captured for the account at fetch time (shape is provider-specific).

Accounts are discovered, not created here. They are written when the tenant-accounts fetch runs for a connection (GET /v1/external/data-providers/{dataProviderId}/tenants — note that route takes the provider id, not the slug). A connection that has never been refreshed simply has no accounts, and archived accounts are never returned.
Visibility follows the connection. Accounts reached through a tenant connection are visible to the whole tenant; accounts reached through a user's OAuth2 connection are visible only to that user — so an empty list can also mean "they belong to someone else's connection".

Critical rules

Connectors = slug; actions = slug + key. There is no connector id or action id in these commands. Get the slug from list-connectors, the action key from get-connector/get-action.
Connections are not created here. list-connections only reads. If none exists, the provider must be connected via the Docyrus UI / OAuth flow (or the raw API) before run-action/curl can authenticate. Treat an empty tenantScope + userScope.connected:false as "not connected yet."
Connection auto-selection: with no --connectionId, the tenant's first connection for that provider is used. For OAuth2 authorization_code providers, --connectionId is ignored and the current user's connection (or a shared one) is used. Pass --connectionId only to disambiguate among multiple tenant connections.
run-action --params must be a JSON object (not an array/primitive) — the CLI rejects otherwise — and is validated server-side against the action's inputJsonSchema (400 "Action input validation failed" with AJV errors).
run-action needs the Automations.Run scope; read commands need Connectors.Read.All. A session that can list connectors may not be allowed to run actions.
curl is an RPC passthrough (PUT /connectors/{slug} with the endpoint in the body) — you pass the external method via -X, not the API method. An absolute endpoint bypasses the connector's base URL.
Never invent a connectionAccountId. It is the id of a connection-accounts row, not the provider's own account id (accountId) and not a connection id. List them first when the provider has sub-accounts.
Always --dryRun a run-action first when the side effect is real (sending email/SMS, posting data) to confirm the resolved request before executing.
The action must exist and be active (provider slug + action key, status=1) — otherwise 404.

Test / validate

Read commands are safe to run anytime; action runs have real side effects (gate with --dryRun).

Discover round-trip: list-connectors → pick a slug → get-connector <slug> shows its actions[] → get-action <slug> <key> shows the input schema. Confirms the connector + action exist and what params they need.
Connection check: list-connections <slug> — confirm a usable connection (tenantScope non-empty or userScope.connected:true) before attempting a run.
Account check (only when the run targets a sub-account): docyrus curl "/v1/connectors/<slug>/connection-accounts" --format json — take the id of the intended row as --connectionAccountId.
Dry-run: run-action <slug> <key> -p '<params>' --dryRun returns { dryRun:true, method, path, headers, body } and sends nothing — verify the params/connection resolve as expected.
Execute only when the dry-run looks right and the side effect is intended; inspect the returned { data, status }.

References

references/connector-model-and-actions.md — Full command reference (args/flags/paths), the connector/connection/account/action data model, the supported auth types, how run-action resolves a connection (tenant vs per-user OAuth2), run-action vs curl mechanics, and the gotchas (header-vs-body selectors, scopes, connection creation outside the CLI).
docyrus-automation-design — the external-action/http-request automation nodes that run connectors inside a workflow. docyrus-app-ai-tools — app-scoped AI tools. docyrus-cli-app — the full CLI command index. docyrus-platform → references/integrations-and-events.md — the integrations/events concept overview.

docyrus-integrations-and-connectors