CLI administration

ventstreamctl is the command-line administration client for VentStream Cloud. Use it to manage organization-scoped environments, pipelines, configuration revisions, agent deployments, lifecycle operations, and runtime status. The CLI sends authenticated HTTPS requests to the managed control plane. It never connects directly to an engine, source database, sink, Kubernetes API, or agent gateway.

A standalone engine has no Cloud management connection and cannot be administered with ventstreamctl. Use the CLI for engines enrolled as managed agents in VentStream Cloud.

Install

ventstreamctl binaries are published in the VentStream releases repository.

Operating system	Architectures
macOS	Apple Silicon (`arm64`) and Intel (`amd64`)
Linux	`arm64` and `amd64`
Windows	`amd64`

macOS and Linux

Install the latest release:

curl -fsSL \
  https://raw.githubusercontent.com/ventstream/ventstream-releases/main/install.sh |
  sh

export PATH="$HOME/.local/bin:$PATH"
ventstreamctl --version

The installer detects the operating system and architecture, downloads the matching archive and SHA256SUMS, verifies the archive checksum and binary version, and stages the executable into $HOME/.local/bin. It does not use sudo, modify a shell profile, or send GitHub credentials. To use a different install directory:

curl -fsSL \
  https://raw.githubusercontent.com/ventstream/ventstream-releases/main/install.sh |
  VENTSTREAMCTL_INSTALL_DIR="$HOME/bin" sh

Rerun the installer to upgrade to the latest release. For a reproducible installation, pin both the installer and binary version:

VERSION=0.2.8
curl -fsSL \
  "https://raw.githubusercontent.com/ventstream/ventstream-releases/v${VERSION}/install.sh" |
  VENTSTREAMCTL_VERSION="$VERSION" sh

Replace 0.2.8 with the release selected for your environment.

Windows

Download ventstreamctl-<version>-windows-amd64.zip from GitHub Releases, extract ventstreamctl.exe, and place it in a directory on PATH.

Verify a release

The installer performs checksum verification automatically. For manual checksum, immutable-release, attestation, and SBOM verification, follow the verification guide. The CLI requires a VentStream Cloud workspace, its control-plane URL, and an authorized user account.

Authenticate

Create an account at ventstream.dev/signup, or accept an organization invitation. Then sign in through the browser. The CLI stores the resulting session in a named profile and prompts for an organization and environment when more than one is available:

ventstreamctl auth login \
  --control-plane <control-plane-url> \
  --profile production

ventstreamctl auth status
ventstreamctl auth whoami

For a non-interactive terminal, add --organization <uuid|short-id|slug> and --environment <uuid|short-id|slug>. The complete browser, enterprise OIDC, account lifecycle, recovery, refresh, and logout behavior is covered in Authentication.

Profiles and context

A profile stores the control-plane origin, credentials, and optional organization and environment defaults. Use separate profiles for separate control planes or identities:

ventstreamctl config use-profile production
ventstreamctl config show

Login normally selects the context. To change it later, list the organizations visible to the authenticated principal and select one:

ventstreamctl orgs list
ventstreamctl config set-org <organization-id>

Then list and select an environment:

ventstreamctl environments list
ventstreamctl config set-env <environment-id>
ventstreamctl config show

After context is selected, routine commands do not need repeated URLs or UUIDs:

ventstreamctl pipelines list
ventstreamctl agents list --pipeline orders-cdc
ventstreamctl operations list --status running

Use --profile <name> for a one-command profile override. Use --organization and --environment only for a one-command context override.

Organizations and environments

Create organizations, accept invitations, and manage members from the VentStream Cloud dashboard. The CLI lists the organizations available to the authenticated account and stores one as its working context. Organization owners can create another environment from the CLI:

ventstreamctl environments create staging \
  --display-name "Staging"

Users can belong to multiple organizations. Invitations, membership, roles, billing, and organization settings remain dashboard workflows; the CLI stays focused on pipeline and agent operations.

Pipelines

Create one logical workload in the selected environment:

ventstreamctl pipelines create orders-cdc \
  --description "Orders search projection" \
  --workload-kind cdc \
  --source-kind postgres \
  --sink-kind opensearch

ventstreamctl pipelines list
ventstreamctl pipelines describe orders-cdc

Pipeline arguments accept an exact name, full UUID, or unambiguous UUID prefix of at least eight characters within the selected environment.

Lifecycle

Lifecycle mutations create durable operations:

ventstreamctl pipelines pause orders-cdc \
  --reason "schema maintenance" --wait

ventstreamctl pipelines resume orders-cdc --wait

ventstreamctl pipelines drain orders-cdc \
  --reason "retire source" --wait

ventstreamctl pipelines reconcile orders-cdc \
  --reason "verify sink parity" --wait

ventstreamctl pipelines rebootstrap orders-cdc \
  --reason "replace source history" --confirm --wait

--wait returns success only when the operation reaches succeeded. Without it, the command returns after the operation is durably queued. rebootstrap is destructive and requires both --reason and --confirm. Use --expected-revision for explicit CI concurrency control. Interactive use can omit it; the CLI reads the current revision and supplies the required If-Match value.

Managed configuration

Create an immutable configuration revision from a canonical ventstream.yaml and its referenced non-secret files:

ventstreamctl pipelines configurations create orders-cdc \
  --engine-config ./ventstream.yaml \
  --file projections/orders.yaml=./orders.yaml \
  --file graphql/schema.graphql=./schema.graphql

Then validate and select it:

ventstreamctl pipelines configurations list orders-cdc
ventstreamctl pipelines configurations validate orders-cdc <revision> \
  --reason "pre-deployment validation"
ventstreamctl pipelines configurations select orders-cdc <revision> \
  --reason "release 2026-07" --wait
ventstreamctl pipelines resume orders-cdc --wait

Selecting a valid revision activates it and delivers it to connected deployments. It does not implicitly resume a paused pipeline. Use apply only when the active revision must be delivered again without creating or selecting a new revision. Roll back to an earlier valid revision:

ventstreamctl pipelines configurations rollback orders-cdc <previous-revision> \
  --reason "rollback failed release" --wait

See Managed configuration for the bundle and secret boundary.

Deployments and enrollment

The CLI calls engine installations deployments under the agents command group. VentStream Cloud stores desired state and identity, while Kubernetes, Docker Compose, or another scheduler creates the actual workload. The CLI does not deploy pods or connect to your cluster.

ventstreamctl agents create orders-primary --pipeline orders-cdc
ventstreamctl agents list --pipeline orders-cdc
ventstreamctl agents describe <deployment-id> --pipeline orders-cdc

Generate a non-secret, version-pinned deployment manifest from the Cloud installation profile:

ventstreamctl agents manifest orders-primary \
  --pipeline orders-cdc \
  --target helm \
  --engine-secret orders-engine-secrets \
  --enrollment-secret orders-enrollment \
  --output orders-primary.values.yaml

Use --target docker-compose for a Docker Compose deployment. See Managed agent on Kubernetes for the complete customer-side installation workflow. Generate one short-lived, single-use enrollment grant:

ventstreamctl agents enroll-token create <deployment-id> \
  --pipeline orders-cdc

The token command prints only the secret to stdout and deliberately has no table or JSON wrapper. Send it directly to a secret-management workflow; do not log it. After the workload enrolls, inspect aggregate and per-instance health:

ventstreamctl agents status \
  --pipeline orders-cdc \
  --deployment <deployment-id>

Irreversibly revoke active workload identities when a deployment is retired or compromised:

ventstreamctl agents identity revoke <deployment-id> \
  --pipeline orders-cdc \
  --reason "host retired" \
  --confirm

Revocation requires re-enrollment before that deployment can reconnect. See Agent enrollment.

Operations

List operation history for the selected environment or one pipeline:

ventstreamctl operations list
ventstreamctl operations list --pipeline orders-cdc --status running

Inspect terminal results and delivery attempts:

ventstreamctl operations describe <operation-id> --attempts
ventstreamctl operations describe <operation-id> --wait
ventstreamctl operations attempts <operation-id>

Only a queued operation can be canceled. Cancellation does not roll back desired state; issue a new lifecycle action when desired state must change.

ventstreamctl operations cancel <operation-id> \
  --reason "request withdrawn"

Automation

Add --output json to commands that support structured output.
Collection commands accept --limit and an opaque --cursor returned by the preceding page.
Set VENTSTREAMCTL_PROFILE to select a profile without a command-line flag.
Set VENTSTREAMCTL_ACCESS_TOKEN to provide a short-lived OIDC access token in ephemeral automation.
Use --idempotency-key when a workflow needs a stable retry identity; otherwise the CLI creates one.
Waited commands exit non-zero for failed, canceled, expired, or timed-out operations.

Run ventstreamctl <group> <command> --help for every supported flag and default.

Get started

Concepts

Connectors

Guides

Engineering

VentStream Cloud

Deploy

Reference

Install

macOS and Linux

Windows

Verify a release

Authenticate

Profiles and context

Organizations and environments

Pipelines

Lifecycle

Managed configuration

Deployments and enrollment

Operations

Automation

​Install

​macOS and Linux

​Windows

​Verify a release

​Authenticate

​Profiles and context

​Organizations and environments

​Pipelines

​Lifecycle

​Managed configuration

​Deployments and enrollment

​Operations

​Automation

Install

macOS and Linux

Windows

Verify a release

Authenticate

Profiles and context

Organizations and environments

Pipelines

Lifecycle

Managed configuration

Deployments and enrollment

Operations

Automation