Registry CLI Reference

Reference for the conduit connectors command group, which manages standalone connectors: the registry install/uninstall/audit/bundle lifecycle, plus listing, describing, and scaffolding new connectors. connector is an accepted alias for connectors.

Every command supports --json, which emits the result as structured JSON (and structured errors) instead of the human-readable table. Commands fall into two groups:

• Offline commands — install, uninstall, audit, bundle, new — operate on your connectors directory on disk and do not require a running Conduit. (uninstall opportunistically contacts a running engine for its in-use check but does not require one.)
• Engine commands — list, describe — read from a running Conduit instance over the API.

Common flags

Flag	Commands	Description
--connectors.path	install, uninstall, list, audit	Connectors directory. Env: CONDUIT_CONNECTORS_PATH. Default <basePath>/connectors.
--config.path	all	Path to the Conduit configuration file.
--json	all	Emit structured JSON instead of a table.

Exit codes

The registry commands use Conduit's deterministic exit codes:

Code	Category	Meaning
0	—	Success.
1	Runtime	Internal error; corrupt download (registry.corrupt_download, sha256 mismatch); malformed artifact archive (registry.archive_invalid); index integrity failure (registry.index_integrity); this build's trust anchors could not be loaded (registry.trust_anchors_unavailable).
2	Validation	Connector, version or platform artifact not found; incompatible version; yanked version; stale, rolled-back or too-new index; stale bundle; index signed by a key this build does not know (registry.trust_anchor_expired); ambiguous uninstall; connector still used by a pipeline (registry.connector_in_use).
3	Environment	Index unreachable, download failed, install lock held; index or bundle over its size cap; artifact trust rejections: unsigned or mis-signed, invalid provenance, revoked or too-loosely-pinned publisher identity (registry.identity_revoked, ...), or --allow-unsigned refused by policy.

The bucket comes from each error code's category, so read the error code, not just the exit code. audit reports the worst finding across all installed connectors.

install

conduit connectors install <name>[@version] [flags]

Installs a connector from the registry into --connectors.path. Resolves the name exactly, selects the newest compatible version when @version is omitted, and verifies the index signature, the artifact's signature and SLSA provenance, and the sha256 digest before writing anything. Verification is fail-closed. See Installing Connectors for the full walkthrough.

Flag	Description
--index-url	Registry index URL. Default https://registry.conduitdata.io/index.json.
--index-file	Read the index from a local file instead of --index-url (offline).
--lock-timeout	Max time to wait for the per-connector install lock. Default 30s.
--dry-run	Resolve and select a platform artifact; report what would be installed without downloading or writing.
--bundle	Install fully offline from a bundle tarball; ignores the positional <name>[@version]. See Offline install.
--allow-unsigned	Skip signature/provenance verification (never the index or sha256 checks). Requires interactive confirmation or CONDUIT_ALLOW_UNSIGNED_INSTALL=I_UNDERSTAND; disabled entirely by operator policy install.allow-unsigned.
--allow-stale-bundle	With --bundle, tolerate a snapshot older than --max-staleness. Same gating as --allow-unsigned; env CONDUIT_ALLOW_STALE_BUNDLE=I_UNDERSTAND; operator policy install.allow-stale-bundle.

uninstall

conduit connectors uninstall <name>[@version] [flags]

Removes a connector artifact and its install-manifest entry. If more than one version of <name> is installed, an explicit @version is required — an ambiguous request refuses rather than guessing.

Before removing anything, uninstall checks whether any pipeline references the exact name@version. It considers both pipelines on a reachable running engine and pipelines merely provisioned on disk (--pipelines.path); it falls back to the on-disk scan when no engine is reachable. By default an in-use connector refuses removal with the affected pipelines listed.

Flag	Description
--force	Remove the artifact even if a pipeline still references it. The affected pipelines are still named in the result as a warning.

list

conduit connectors list [flags]

Aliases: ls. By default, lists the connector instances registered in a running Conduit (requires the engine to be running), optionally filtered by pipeline.

With --installed, it instead lists installed connector plugin artifacts from the local install manifest under --connectors.path — a different thing from pipeline instances, shown as a distinct table (NAME, INSTALLED, SIGNED, INSTALLED_AT, LATEST_AVAILABLE, STATUS).

Flag	Description
--pipeline-id	Filter connector instances by pipeline ID. Mutually exclusive with --installed.
--installed	List installed plugin artifacts from the local manifest instead of pipeline instances.
--index-url	Registry index URL, consulted only with --installed for a best-effort LATEST_AVAILABLE column. Default https://registry.conduitdata.io/index.json.
--index-file	Read the index from a local file instead of --index-url; consulted only with --installed.

note

--installed reads the local manifest, but this command still dials the engine first like every other connectors list invocation, so a reachable engine is currently required even in --installed mode. If the index is unreachable, the LATEST_AVAILABLE/STATUS columns are informational-only for that run.

audit

conduit connectors audit [flags]

Re-verifies every installed connector against the current registry index — the protection for connectors installed before a version was yanked or a publisher was revoked. It re-fetches and re-verifies the signed index through the same pipeline install uses (there is no lower-trust audit-only fetch), then reports per connector:

• YANKED_VERSION, REVOKED_PUBLISHER — registry-trust failures (Fail).
• DELISTED, UNKNOWN_VERSION — registry-trust warnings (Warn).
• MISSING_ARTIFACT, DRIFTED — local-integrity warnings (Warn).

An index that cannot be fetched or cryptographically verified fails the whole run (never a per-connector finding) — an audit built on an unverified index cannot be trusted. Check the reported error code; this is distinct from "all clean".

Flag	Description
--index-url	Registry index URL. Default https://registry.conduitdata.io/index.json.
--index-file	Read the index from a local file instead of --index-url (offline).
--max-staleness	Maximum age of a verified index before it is considered stale. Defaults to install.max-staleness (7 days).

bundle

conduit connectors bundle <name>[@version] [flags]

Prepares a self-contained offline-install tarball on a networked machine, running the same full verification a normal install would before writing it. See Air-gapped / offline install.

Flag	Description
--os	Target operating system. Defaults to this host's.
--arch	Target architecture. Defaults to this host's.
--output	Output bundle path. Defaults to <name>-<version>-<os>-<arch>.bundle.tar.gz.
--index-url	Registry index URL. Default https://registry.conduitdata.io/index.json.
--index-file	Read the index from a local file instead of --index-url.

describe

conduit connectors describe CONNECTOR_ID [flags]

Aliases: desc. Shows the detail view of a connector instance in a running Conduit — its type, plugin, pipeline, configuration, and attached processors. Requires the engine to be running. List connector IDs with conduit connectors list.

conduit connectors describe connector:source

new

conduit connectors new [name] [flags]

Scaffolds a full Go connector repository from ConduitIO/conduit-connector-template — SDK wiring, tests, CI, release workflow, and the acceptance-test harness — ready to build. It renames the module path, installs the code-gen tool, runs generation, verifies go build ./..., and initializes git.

Flag	Description
--module	Go module path, e.g. github.com/you/conduit-connector-<name> (required).
--lang	Target language: go (default) or python. python scaffolds connectors only, and the generated conduitio dependency does not install from PyPI yet.
--path	Destination directory. Default ./conduit-connector-<name>.
--sdk-version	Override the SDK version pinned in the embedded template.
--git / --no-git	Initialize a git repository and first commit (--git is the default).
--skip-generate	Skip the code-gen tool install and generation step (the template ships pre-generated output, so it still builds).
--yes, -y	Confirm without prompting.
--force	Overwrite the destination directory if it already exists.

conduit connectors new s3 --module github.com/you/conduit-connector-s3