Skip to main content

connectors

Generated by connectors-docs from the definition the connectors binary parses: the command tree that ESS generates from the CLI binding apps/connectors/spec/cli.yaml, as apps/connectors/src/help.rs presents it. It lists only commands that exist. connectors --version prints the version, and --help after any command prints its usage.

Local integration access through explicitly configured connector instances. After an upgrade, connectors setup owner-stop stops the owner an older binary started

Global options​

Every command accepts these, anywhere on the command line.

ArgumentRequiredDefaultValuesMeaning
--config <global_config>nononeany
--state-dir <global_state>nononeany
--output <global_output>nohumanhuman, json

Commands​

CommandWhat it does
connectors adapters describeDeprecated name of connectors instances describe
connectors adapters listDeprecated name of connectors instances list
connectors adapters statusDeprecated name of connectors instances status
connectors adapters stopDeprecated name of connectors instances stop
connectors approvals clock-checkCheck the configured authenticated clock without starting services
connectors approvals issueApprove the exact reconstructed subject and publish a new protected proof file
connectors approvals key-initCreate a new approval-signing key in protected local custody
connectors approvals key-recoverConfirm and publish an exact staged approval-signing key
connectors approvals key-retireDelete exact noncurrent signing material while retaining public history
connectors approvals key-revokeRevoke the current key and cancel its pending replacement
connectors approvals key-rotatePublish a replacement for the exact current approval-signing key
connectors approvals key-statusObserve public key metadata without starting services or reading secrets
connectors approvals policy-setPublish the exact permitted write-operation set under revision control
connectors approvals policy-statusInspect retained local write policy without starting services
connectors approvals prepareResolve the exact approval subject without provider or credential access
connectors connections connectBegin admitted local protected credential acquisition on /; --endpoint first writes that instance's endpoint into the configuration
connectors connections describeInspect safe metadata for one connection
connectors connections launchRun a pinned consumer with one connection's credential on descriptor 3
connectors connections listList safe connection metadata
connectors connections reconnectPublish a new credential on the exact connection without changing its identity; connections repair is its deprecated name
connectors connections repairDeprecated name of connectors connections reconnect
connectors connections revalidateRevalidate the saved credential without re-entry
connectors connections revokeCommit terminal local revocation under the current fence
connectors connections statusObserve exactly one connection or acquisition
connectors connections tokenIssue a current access token of one OAuth2 connection, printed only with --reveal
connectors definitions installFetch the connectors-definitions release TAG from SOURCE (an https repository URL or a local directory), check every file against its index.json, and record it in definitions.lock and a read-only cache; grants nothing and starts no process
connectors instances describeInspect one configured instance and its cached descriptor; adapters describe is its deprecated name
connectors instances listList configured instances; adapters list is its deprecated name
connectors instances statusObserve the lifecycle owner of the process that serves one instance; adapters status is its deprecated name
connectors instances stopStop only the exact owned incarnation of the process that serves one instance; adapters stop is its deprecated name
connectors invokeInvoke one operation of a connector's instance; the instance, connection, schema and revision default to the only ones that fit
connectors listList every connector this build ships, with its auth profiles and the instances the configuration names; needs no configuration and starts no process
connectors operations describeInspect an operation and its exact schema identity
connectors operations listList operations from selected cached metadata
connectors setup checkCheck local configuration and prerequisites without authentication
connectors setup checkpoints-enableEnable durable open checkpoints on the existing store; one-way, connectors 0.32.0 and earlier can no longer open it
connectors setup initCreate private local configuration without starting services
connectors setup migrateRewrite each entry of the legacy configuration format that maps to a shipped connector as that connector's instance, keeping its instance id and revision, in the short form when the installed provider derives it unchanged; --mode dry-run (or --dry-run) prints the new file, --mode apply (or --apply) writes it and keeps the old one as config.toml.before-migrate-TIMESTAMP (UTC)
connectors setup owner-stopStop this state directory's running owner, of any build, within 30 seconds; run it after an upgrade when a command answers next_action stop_owner
connectors completionsEmit shell completions

connectors adapters describe​

Deprecated name of connectors instances describe

connectors adapters describe [OPTIONS] (deprecated; use connectors instances describe)
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors adapters list​

Deprecated name of connectors instances list

connectors adapters list [OPTIONS] (deprecated; use connectors instances list)
ArgumentRequiredDefaultValuesMeaning
--limit <field:limit>nononeany
--cursor <field:cursor>nononeany

connectors adapters status​

Deprecated name of connectors instances status

connectors adapters status [OPTIONS] (deprecated; use connectors instances status)
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors adapters stop​

Deprecated name of connectors instances stop

connectors adapters stop [OPTIONS] --expected-revision <field:expected_revision> --host-incarnation <field:host_incarnation> --child-incarnation <field:child_incarnation> (deprecated; use connectors instances stop)
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--host-incarnation <field:host_incarnation>yesnoneany
--child-incarnation <field:child_incarnation>yesnoneany

connectors approvals clock-check​

Check the configured authenticated clock without starting services

connectors approvals clock-check [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors approvals issue​

Approve the exact reconstructed subject and publish a new protected proof file

connectors approvals issue [OPTIONS] --connection <field:connection> --operation <field:operation> --schema <field:schema> --revision <field:revision> --approve-subject <field:approve_subject> --proof-output <field:proof_output> <--input-json <source:input:inline>|--input-file <source:input:file>|--input-stdin>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>yesnoneany
--operation <field:operation>yesnoneany
--schema <field:schema>yesnoneany
--revision <field:revision>yesnoneany
--input-json <source:input:inline>nononeany
--input-file <source:input:file>nononeany
--input-stdinnofalseany
--approve-subject <field:approve_subject>yesnoneany
--proof-output <field:proof_output>yesnoneany

connectors approvals key-init​

Create a new approval-signing key in protected local custody

connectors approvals key-init [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>nononeany

connectors approvals key-recover​

Confirm and publish an exact staged approval-signing key

connectors approvals key-recover [OPTIONS] --expected-revision <field:expected_revision> --candidate <field:candidate>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--candidate <field:candidate>yesnoneany

connectors approvals key-retire​

Delete exact noncurrent signing material while retaining public history

connectors approvals key-retire [OPTIONS] --expected-revision <field:expected_revision> --key <field:key>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--key <field:key>yesnoneany

connectors approvals key-revoke​

Revoke the current key and cancel its pending replacement

connectors approvals key-revoke [OPTIONS] --expected-revision <field:expected_revision> --expected-key <field:expected_key>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--expected-key <field:expected_key>yesnoneany

connectors approvals key-rotate​

Publish a replacement for the exact current approval-signing key

connectors approvals key-rotate [OPTIONS] --expected-revision <field:expected_revision> --expected-key <field:expected_key>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--expected-key <field:expected_key>yesnoneany

connectors approvals key-status​

Observe public key metadata without starting services or reading secrets

connectors approvals key-status [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors approvals policy-set​

Publish the exact permitted write-operation set under revision control

connectors approvals policy-set [OPTIONS] --input-file <field:input_file>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>nononeany
--input-file <field:input_file>yesnoneany

connectors approvals policy-status​

Inspect retained local write policy without starting services

connectors approvals policy-status [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors approvals prepare​

Resolve the exact approval subject without provider or credential access

connectors approvals prepare [OPTIONS] --connection <field:connection> --operation <field:operation> --schema <field:schema> --revision <field:revision> <--input-json <source:input:inline>|--input-file <source:input:file>|--input-stdin>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>yesnoneany
--operation <field:operation>yesnoneany
--schema <field:schema>yesnoneany
--revision <field:revision>yesnoneany
--input-json <source:input:inline>nononeany
--input-file <source:input:file>nononeany
--input-stdinnofalseany

connectors connections connect​

Begin admitted local protected credential acquisition on /; --endpoint first writes that instance's endpoint into the configuration

connectors connections connect [OPTIONS] --profile <field:profile> [field:target]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--profile <field:profile>yesnoneany
--device <field:device>nononeany
--credential-file <source:credential_document:file>nononeany
--credential-stdinnofalseany
--credential-promptnofalseany
<field:target>nononeany
--endpoint <field:endpoint>nononeany

connectors connections describe​

Inspect safe metadata for one connection

connectors connections describe [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany

connectors connections launch​

Run a pinned consumer with one connection's credential on descriptor 3

connectors connections launch [OPTIONS] --consumer <field:consumer>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--consumer <field:consumer>yesnoneany
--args <field:args>nononeany

connectors connections list​

List safe connection metadata

connectors connections list [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--limit <field:limit>nononeany
--cursor <field:cursor>nononeany

connectors connections reconnect​

Publish a new credential on the exact connection without changing its identity; connections repair is its deprecated name

connectors connections reconnect [OPTIONS] --expected-revision <field:expected_revision>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--expected-revision <field:expected_revision>yesnoneany
--device <field:device>nononeany
--credential-file <source:credential_document:file>nononeany
--credential-stdinnofalseany
--credential-promptnofalseany

connectors connections repair​

Deprecated name of connectors connections reconnect

connectors connections repair [OPTIONS] --expected-revision <field:expected_revision> (deprecated; use connectors connections reconnect)
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--expected-revision <field:expected_revision>yesnoneany
--device <field:device>nononeany
--credential-file <source:credential_document:file>nononeany
--credential-stdinnofalseany
--credential-promptnofalseany

connectors connections revalidate​

Revalidate the saved credential without re-entry

connectors connections revalidate [OPTIONS] --expected-revision <field:expected_revision>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--expected-revision <field:expected_revision>yesnoneany

connectors connections revoke​

Commit terminal local revocation under the current fence

connectors connections revoke [OPTIONS] --expected-revision <field:expected_revision>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--expected-revision <field:expected_revision>yesnoneany

connectors connections status​

Observe exactly one connection or acquisition

connectors connections status [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--acquisition <field:acquisition>nononeany

connectors connections token​

Issue a current access token of one OAuth2 connection, printed only with --reveal

connectors connections token [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--reveal <field:reveal>nononeany

connectors definitions install​

Fetch the connectors-definitions release TAG from SOURCE (an https repository URL or a local directory), check every file against its index.json, and record it in definitions.lock and a read-only cache; grants nothing and starts no process

connectors definitions install [OPTIONS] --source <field:source> --tag <field:tag>
ArgumentRequiredDefaultValuesMeaning
--source <field:source>yesnoneany
--tag <field:tag>yesnoneany

connectors instances describe​

Inspect one configured instance and its cached descriptor; adapters describe is its deprecated name

connectors instances describe [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors instances list​

List configured instances; adapters list is its deprecated name

connectors instances list [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--limit <field:limit>nononeany
--cursor <field:cursor>nononeany

connectors instances status​

Observe the lifecycle owner of the process that serves one instance; adapters status is its deprecated name

connectors instances status [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany

connectors instances stop​

Stop only the exact owned incarnation of the process that serves one instance; adapters stop is its deprecated name

connectors instances stop [OPTIONS] --expected-revision <field:expected_revision> --host-incarnation <field:host_incarnation> --child-incarnation <field:child_incarnation>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--expected-revision <field:expected_revision>yesnoneany
--host-incarnation <field:host_incarnation>yesnoneany
--child-incarnation <field:child_incarnation>yesnoneany

connectors invoke​

Invoke one operation of a connector's instance; the instance, connection, schema and revision default to the only ones that fit

connectors invoke [OPTIONS] [CONNECTOR[/INSTANCE]] <OPERATION>
ArgumentRequiredDefaultValuesMeaning
<CONNECTOR[/INSTANCE]>nononeanyThe connector, and after one / its instance; the instance may be left out when the connector has only one; with --definition the target may be left out, the file naming the connector
<OPERATION>yesnoneanyThe operation to invoke
--connection <field:connection>nononeanyThe connection to invoke through; the instance's only usable one when left out
--schema <field:schema>nononeanyA pin: the operation's schema identity, refused when the current description differs; taken from it when left out
--revision <field:revision>nononeanyA pin: the description's revision, refused when the current description differs; taken from it when left out
--input-json <source:input:inline>nononeanyThe input document, as JSON text
--input-file <source:input:file>nononeanyA file holding the input document
--input-stdinnofalseanyRead the input document from standard input, as happens when no input flag is given
--approval-file <field:approval_file>nononeanyThe approval proof a write is invoked with
--idempotency-key <field:idempotency_key>nononeanyA write's idempotency key
--definition <field:definition>nononeanyA connectors-definition/1 file to invoke without configuring it; a target, when given, names its connector
--definitions-root <field:definitions_root>nononeanyWith --definition: the tree holding its vendored source and shared auth files [default: the parent of the file's directory]
--credential-file <field:credential_file>nononeanyWith --definition: the OAuth client file to connect with when the instance has no connection
--describe <field:describe>nononeanytrue: print the operation's description, effect, schema and revision, and invoke nothing
--fields <field:fields>nononeanyPrint only these members of the provider result: comma-separated paths such as ticket.id, events[].field_name, alias:path or the pointer /page[after]; unmatched paths are listed in missing
--each <field:each>nononeanyPrint one JSON line per element of the array at this path, each shaped by --fields, then the envelope; refused on a write
--walk <field:walk>nononeanytrue: read every page of the walk the read declares, one invoke per page, writing each record as one JSON line to --out, then print a summary
--max-pages <field:max_pages>nononeanyWith --walk: the most pages read, 1 to 10000 [default: 20]; a walk stopped there names its next input in resume
--out <field:out>nononeanyWith --walk: a new file the records are written to, owner-only, or - for standard output

connectors list​

List every connector this build ships, with its auth profiles and the instances the configuration names; needs no configuration and starts no process

connectors list [OPTIONS]

connectors operations describe​

Inspect an operation and its exact schema identity

connectors operations describe [OPTIONS] --operation <field:operation>
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--operation <field:operation>yesnoneany

connectors operations list​

List operations from selected cached metadata

connectors operations list [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--adapter <ALIAS>nononeanyDeprecated: the alias of a configured entry; select with --connector and --instance
--connector <field:connector>nononeany
--instance <field:instance>nononeany
--connection <field:connection>nononeany
--family <field:family>nononeany
--limit <field:limit>nononeany
--cursor <field:cursor>nononeany

connectors setup check​

Check local configuration and prerequisites without authentication

connectors setup check [OPTIONS]

connectors setup checkpoints-enable​

Enable durable open checkpoints on the existing store; one-way, connectors 0.32.0 and earlier can no longer open it

connectors setup checkpoints-enable [OPTIONS]
ArgumentRequiredDefaultValuesMeaning
--confirm <field:confirm>nononeany

connectors setup init​

Create private local configuration without starting services

connectors setup init [OPTIONS]

connectors setup migrate​

Rewrite each entry of the legacy configuration format that maps to a shipped connector as that connector's instance, keeping its instance id and revision, in the short form when the installed provider derives it unchanged; --mode dry-run (or --dry-run) prints the new file, --mode apply (or --apply) writes it and keeps the old one as config.toml.before-migrate-TIMESTAMP (UTC)

connectors setup migrate [OPTIONS] --mode <field:mode>
ArgumentRequiredDefaultValuesMeaning
--mode <field:mode>yesnoneany

connectors setup owner-stop​

Stop this state directory's running owner, of any build, within 30 seconds; run it after an upgrade when a command answers next_action stop_owner

connectors setup owner-stop [OPTIONS]

connectors completions​

Emit shell completions

connectors completions [OPTIONS] <shell>
ArgumentRequiredDefaultValuesMeaning
<shell>yesnonebash