> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bijection integration

> Manage integration connections, sources and syncs

Commands for managing third-party integrations: credentials, connections,
sources, syncs, listeners and connected accounts.

For a walkthrough, see [Connecting and syncing](/integrations/connections).

## Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration [options] [command]
```

## Deployment selection

Every subcommand acts on your dev deployment by default and accepts:

<dl>
  <dt>`--prod`</dt>

  <dd>
    Act on this project's default production deployment.
  </dd>

  <dt>`--deployment <deployment>`</dt>

  <dd>
    Act on a specific deployment. Accepts a deployment name (e.g.
    joyful-capybara-123), a deployment reference (e.g. dev/james, staging),
    `dev` or `prod`.
  </dd>
</dl>

## Subcommands

| Area | Subcommands |
| - | - |
| Credentials | [`credential-create`](#credential-create), [`credential-rotate`](#credential-rotate), [`credential-status`](#credential-status) |
| Connections | [`configure`](#configure), [`identify`](#identify), [`install`](#install), [`role-bind`](#role-bind), [`activate`](#activate) |
| Work | [`capture`](#capture), [`run`](#run), [`cancel`](#cancel), [`status`](#status) |
| Sources | [`sources`](#sources), [`source-status`](#source-status), [`refresh`](#refresh), [`resume`](#resume), [`cancel-source`](#cancel-source), [`refresh-repair`](#refresh-repair) |
| Native sources | [`postgres-control`](#postgres-control), [`mail-repair`](#mail-repair) |
| Listeners | [`listener-configure`](#listener-configure), [`listener-status`](#listener-status) |
| Webhook events | [`webhook-configure`](#webhook-configure), [`webhook-status`](#webhook-status), [`webhook-event`](#webhook-event), [`webhook-control`](#webhook-control) |
| Commands | [`command-status`](#command-status), [`command-recover`](#command-recover) |
| Connected accounts | [`account-authorize`](#account-authorize), [`account-callback`](#account-callback), [`account-resources`](#account-resources), [`account-select`](#account-select), [`account-status`](#account-status), [`account-pause`](#account-pause), [`account-resume`](#account-resume), [`account-disconnect`](#account-disconnect), [`account-erase`](#account-erase) |

## Credentials

Credential values are read from piped stdin or from `--from-file`, never from
an argument or an interactive terminal. Input is limited to 8 KiB of valid
UTF-8 and must arrive within 30 seconds. All bytes are preserved, including a
terminal newline: use `printf` instead of `echo` when no newline is intended.
Values are never printed.

### `credential-create`

Create a private integration credential.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration credential-create [options] <name>
```

<dl>
  <dt>`<name>`</dt>

  <dd>
    Private credential name.
  </dd>

  <dt>`--from-file <file>`</dt>

  <dd>
    Read the exact UTF-8 credential from a file instead of piped stdin.
  </dd>
</dl>

### `credential-rotate`

Rotate an existing private integration credential. Takes the same arguments as
`credential-create`.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration credential-rotate [options] <name>
```

### `credential-status`

Inspect private credential metadata.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration credential-status [options] <name>
```

## Connections

### `configure`

Configure an admitted integration connection.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration configure [options] <destination>
```

<dl>
  <dt>`<destination>`</dt>

  <dd>
    Installed connection name.
  </dd>

  <dt>`--module <module>`</dt>

  <dd>
    Defining deployed module, including `.js`. Required.
  </dd>

  <dt>`--export <export>`</dt>

  <dd>
    Defining integration export. Required.
  </dd>

  <dt>`--base-url <url>`</dt>

  <dd>
    Provider HTTP base URL; omitted for native integrations such as PostgreSQL
    and mail.
  </dd>

  <dt>`--credential-ref <name>`</dt>

  <dd>
    Private credential created with `bijection integration credential-create`.
  </dd>

  <dt>`--component <path>`</dt>

  <dd>
    Component path; defaults to root.
  </dd>

  <dt>`--setup <key=value>`</dt>

  <dd>
    A setup value this provider's definition declares; repeatable.
  </dd>

  <dt>`--show-setup`</dt>

  <dd>
    Print what this connection has to be told and make no change.
  </dd>
</dl>

Which setup values a provider needs is declared on its integration definition.
Secrets are never supplied this way: create one with `credential-create` and
name it as `--credential-ref`.

### `identify`

Admit identity verification work. Run it afterwards with [`run`](#run).

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration identify [options] <destination> <request-id>
```

<dl>
  <dt>`<destination>`</dt>

  <dd>
    Installed connection name.
  </dd>

  <dt>`<request-id>`</dt>

  <dd>
    Stable work ID; reuse to recover this request.
  </dd>
</dl>

### `install`

Install a verified collection source. Prints the source ID.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration install [options] <destination> <table>
```

<dl>
  <dt>`<destination>`</dt>

  <dd>
    Verified connection name.
  </dd>

  <dt>`<table>`</dt>

  <dd>
    Declared source table.
  </dd>
</dl>

### `role-bind`

Bind one credential role of a configured connection, for a definition whose
HTTP contracts dispatch under named credential roles. The credential envelope
is read from piped stdin or `--from-file`, with the same limits as
`credential-create`. A role belongs to the connection's authorizing account.
Activate the connection afterwards with [`activate`](#activate).

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration role-bind [options] <destination>
```

<dl>
  <dt>`--role <name>`</dt>

  <dd>
    Credential role the definition dispatches under. Required.
  </dd>

  <dt>`--base-url <url>`</dt>

  <dd>
    Provider HTTP base URL for this role. Required.
  </dd>

  <dt>`--capability <name>`</dt>

  <dd>
    Capability this role is granted; repeatable.
  </dd>

  <dt>`--from-file <file>`</dt>

  <dd>
    Read the exact UTF-8 credential envelope from a file instead of piped stdin.
  </dd>
</dl>

### `activate`

Activate a configured connection once it holds every credential role its
definition names.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration activate [options] <destination>
```

## Work

Identity checks and syncs are durable work identified by a request ID.

### `capture`

Admit a source acquisition under a request ID of your choice.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration capture [options] <source> <request-id>
```

<dl>
  <dt>`<source>`</dt>

  <dd>
    Source identity returned by `integration install`.
  </dd>

  <dt>`<request-id>`</dt>

  <dd>
    Stable work ID; reuse to recover this request.
  </dd>
</dl>

### `run`

Run or resume admitted acquisition work.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration run [options] <request-id>
```

### `cancel`

Cancel pending acquisition work.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration cancel [options] <request-id>
```

### `status`

Inspect historical work and publication status.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration status [options] <request-id>
```

## Sources

### `sources`

List installed sources, their connection and acquisition health.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration sources [options]
```

<dl>
  <dt>`--component-id <id>`</dt>

  <dd>
    Component holding the sources; defaults to root.
  </dd>

  <dt>`--cursor <cursor>`</dt>

  <dd>
    Continue from a previous page's `next_cursor`.
  </dd>
</dl>

### `source-status`

Inspect a source's schedule, state, sync history, last connection check and
retained work.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration source-status [options] <source>
```

### `refresh`

Request a current-state refresh: the CLI's **Sync now**. A request made while
one is outstanding joins it.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration refresh [options] <source>
```

### `resume`

Wake an exact blocked or retrying acquisition.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration resume [options] <source> <request-id>
```

<dl>
  <dt>`<request-id>`</dt>

  <dd>
    Work ID reported by `source-status`.
  </dd>
</dl>

### `cancel-source`

Cancel the current source occurrence. Future syncs stay scheduled.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration cancel-source [options] <source> <request-id>
```

### `refresh-repair`

Repair a blocked refresh with currently deployed code.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration refresh-repair [options] <source> <request-id>
```

## Native sources

### `postgres-control`

<Warning>PostgreSQL change data capture is in beta.</Warning>

Stop PostgreSQL acquisition or request a qualified new baseline. See
[PostgreSQL](/integrations/postgres#operating-the-source).

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration postgres-control [options] <destination>
```

<dl>
  <dt>`--revision <revision>`</dt>

  <dd>
    Native revision reported by `source-status`. Required.
  </dd>

  <dt>`--control <control>`</dt>

  <dd>
    `stop` or `rebaseline`. Required.
  </dd>
</dl>

### `mail-repair`

<Warning>Mail integrations are in beta.</Warning>

Retry mail gaps without creating new arrival occurrences. See
[Mail](/integrations/mail#gaps-and-repair).

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration mail-repair [options] <destination>
```

<dl>
  <dt>`--revision <revision>`</dt>

  <dd>
    Mail revision reported by `source-status`. Required.
  </dd>
</dl>

## Listeners

<Warning>Listeners are in beta.</Warning>

### `listener-configure`

Configure automatic refresh from provider notifications. See
[Listeners and webhooks](/integrations/listeners).

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration listener-configure [options] <source>
```

<dl>
  <dt>`--callback-url <url>`</dt>

  <dd>
    Public HTTPS base ending in `/api/integrations/listener`; the endpoint
    segment is appended and reported back. Required exactly for a listener the
    provider delivers to, and refused for one the engine polls.
  </dd>

  <dt>`--signing-credential <name>`</dt>

  <dd>
    Integration credential holding the endpoint's signing secret, where the
    declared scheme verifies signatures.
  </dd>

  <dt>`--disable`</dt>

  <dd>
    Stop notifications and retire registered channels.
  </dd>
</dl>

### `listener-status`

Inspect notification health and refresh responsibility.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration listener-status [options] <source>
```

## Webhook events

<Warning>Webhook events are in beta.</Warning>

### `webhook-configure`

Bind an occurrence listener to one operation.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration webhook-configure [options] <source> <operation>
```

<dl>
  <dt>`<operation>`</dt>

  <dd>
    The operation's address, such as `billing:receiveEvent`.
  </dd>

  <dt>`--types <types>`</dt>

  <dd>
    Comma-separated admitted event types. Required.
  </dd>

  <dt>`--type-field <path>`</dt>

  <dd>
    Dot-separated event-type field. Default: `type`.
  </dd>

  <dt>`--identities <count>`</dt>

  <dd>
    Retained occurrence identities to reserve. They are never collected, so
    this is the deduplication guarantee; raise it later with
    `webhook-control expand`. Default: `10000`.
  </dd>
</dl>

### `webhook-status`

Inspect occurrence custody and retained identity capacity.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration webhook-status [options] <source>
```

### `webhook-event`

Inspect one retained occurrence.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration webhook-event [options] <source> <occurrence>
```

<dl>
  <dt>`--payload`</dt>

  <dd>
    Read the retained payload with deployment authority.
  </dd>
</dl>

### `webhook-control`

Hold, retry, discard, expand capacity, retire or reinstate a feed.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration webhook-control [options] <source> <control>
```

<dl>
  <dt>`<control>`</dt>

  <dd>
    `hold`, `resume`, `retry`, `discard`, `expand`, `retire` or `reinstate`.
  </dd>

  <dt>`--revision <revision>`</dt>

  <dd>
    Control revision from `webhook-status`. Required.
  </dd>

  <dt>`--occurrence <identity>`</dt>

  <dd>
    Exact event for `retry` or `discard`.
  </dd>

  <dt>`--reason <reason>`</dt>

  <dd>
    Required for `discard`, `expand`, `retire` and `reinstate`, and for a
    retry that confirms a changed execution basis.
  </dd>

  <dt>`--basis <basis>`</dt>

  <dd>
    Confirm that this input may run under a program that changed after it was
    admitted. Pass the `handler_basis` `webhook-status` reports, together with
    `--reason`.
  </dd>

  <dt>`--identities <count>`</dt>

  <dd>
    New identity quota for `expand`. It only grows.
  </dd>

  <dt>`--discard-pending`</dt>

  <dd>
    Retire even though inputs are unfinished, discarding them under the same
    reason. This abandons accepted responsibility and records a coverage gap.
  </dd>
</dl>

## Commands

Inspect and recover integration commands your operations submitted as
external calls. See [Operations](/operations/overview).

### `command-status`

Inspect a command's outcome, the destination's own name for a refusal,
recovery bounds and required evidence.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration command-status [options] <operation>
```

<dl>
  <dt>`<operation>`</dt>

  <dd>
    Existing accepted external call ID.
  </dd>
</dl>

### `command-recover`

Recover an existing command from retained evidence or a bounded read.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration command-recover [options] <operation>
```

Recovery preserves the accepted identity and budgets. It does not submit a new
write or treat matching current state as proof of delivery.

## Connected accounts

<Warning>Connected accounts are in beta.</Warning>

These commands act for an application user, named with `--as`. Except for
`account-callback`, they also name the integration with `--module` and
`--export`, and accept `--component <path>`, which defaults to root.

<dl>
  <dt>`--as <token-identifier>`</dt>

  <dd>
    Application user owning the account, as its token identifier
    (`issuer|subject`). Required.
  </dd>

  <dt>`--module <module>`</dt>

  <dd>
    Defining deployed module, including `.js`.
  </dd>

  <dt>`--export <export>`</dt>

  <dd>
    Defining integration export.
  </dd>
</dl>

### `account-authorize`

Connect a provider account for an application user. The provider grants what
it chooses, which may be less than was asked. A single-use authorization code
is never printed or stored.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-authorize [options]
```

<dl>
  <dt>`--redirect-uri <url>`</dt>

  <dd>
    Where the provider returns the user after consent. Required.
  </dd>

  <dt>`--capability <capability>`</dt>

  <dd>
    Requested capability; repeat for several.
  </dd>

  <dt>`--account <handle>`</dt>

  <dd>
    Reconnect this existing account instead of adding one.
  </dd>

  <dt>`--code <code>`</dt>

  <dd>
    Complete without prompting; for scripts that already hold the redirect.
  </dd>

  <dt>`--setup <key=value>`</dt>

  <dd>
    A setup value this provider's definition asks the connecting account for;
    repeatable.
  </dd>
</dl>

### `account-callback`

Complete an authorization started by `account-authorize`.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-callback [options]
```

<dl>
  <dt>`--attempt <attempt>`</dt>

  <dd>
    Attempt reported by `account-authorize`. Required.
  </dd>

  <dt>`--state <state>`</dt>

  <dd>
    State reported by `account-authorize`. Required.
  </dd>

  <dt>`--code <code>`</dt>

  <dd>
    Single-use code from the provider redirect. Required.
  </dd>
</dl>

### `account-resources`

List what an account offers to read.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-resources [options] <account>
```

<dl>
  <dt>`<account>`</dt>

  <dd>
    Account handle reported by `account-authorize`.
  </dd>
</dl>

### `account-select`

Install the resources an account may read. The selection is the complete set
for this account: a resource left out of a later selection is no longer
acquired.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-select [options] <account>
```

<dl>
  <dt>`--resource <resource>`</dt>

  <dd>
    Resource handle reported by `account-resources`; repeat for several.
    Required.
  </dd>
</dl>

### `account-status`

Inspect account state, capabilities and sources.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-status [options] <account>
```

### `account-pause`

Stop acquisition without surrendering authority.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-pause [options] <account>
```

### `account-resume`

Recreate acquisition for a paused account.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-resume [options] <account>
```

### `account-disconnect`

Revoke an account's authority and stop its acquisition. Disconnection is
terminal for this account: reconnecting completes a new authorization and does
not revive this one. Acquired records are kept.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-disconnect [options] <account>
```

<dl>
  <dt>`--yes`</dt>

  <dd>
    Confirm without prompting.
  </dd>
</dl>

### `account-erase`

Erase an account's sources and everything acquired through them. Erasure is
permanent and removes acquired records. It does not undo effects already
delivered to the provider.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration account-erase [options] <account>
```

<dl>
  <dt>`--yes`</dt>

  <dd>
    Confirm without prompting.
  </dd>
</dl>