CLI administration - VentStream

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 attached to VentStream Cloud with a deployment agent key.

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://ventstream.dev/install-cli.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://ventstream.dev/install-cli.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.33
curl -fsSL "https://ventstream.dev/install-cli/v${VERSION}.sh" |
  VENTSTREAMCTL_VERSION="$VERSION" sh

Replace 0.2.33 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.

Authenticate

The CLI requires a VentStream Cloud organization and an authorized user account. 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 --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.

Organization context and environments

The CLI lists the organizations available to the authenticated account and stores one as its working context. Creating organizations, accepting invitations, and managing members happen in the VentStream Cloud dashboard, not the CLI. 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 a UUID, a unique UUID prefix (8+ characters), or the slug/name 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 (plus any referenced non-secret files via --file), then validate and select it:

ventstreamctl pipelines configurations create orders-cdc \
  --engine-config ./ventstream.yaml
ventstreamctl pipelines configurations validate orders-cdc <revision> \
  --reason "pre-deployment validation"
ventstreamctl pipelines configurations select orders-cdc <revision> \
  --reason "release 2026-07" --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:

ventstreamctl pipelines configurations apply orders-cdc <revision> \
  --reason "redeliver after deployment replacement" --wait

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 full worked example, the bundle format, and the secret boundary.

Deployments and agent keys

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

Mint the deployment’s agent key. The key attaches the public engine to this deployment; on first connect the engine performs the enrollment handshake and binds an mTLS identity:

ventstreamctl agents key create orders-primary --pipeline orders-cdc

The key command prints only the secret to stdout and deliberately has no table or JSON wrapper. Pipe it directly into a secret-management workflow — for example | kubectl create secret generic orders-agent-key --from-file=key=/dev/stdin — and do not log it. The key is shown once at mint time; the same key keeps working across restarts until revoked. Minting a new key revokes the previous one, so rotation is a single key create. List key metadata or revoke a key explicitly:

ventstreamctl agents key list orders-primary --pipeline orders-cdc
ventstreamctl agents key revoke orders-primary --pipeline orders-cdc \
  --key <key-id> --confirm

See Managed agent on Kubernetes for the complete customer-side installation workflow. After the workload connects, 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

After identity revocation, the next engine start re-binds through the deployment’s agent key; revoke the key as well to keep the deployment offline. See Agent keys and the enrollment handshake.

Legacy: enrollment tokens

Deployments bootstrapped before agent keys used a short-lived, single-use enrollment grant and a rendered installation manifest. Both remain available through the deprecation window:

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

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

New installations should use agent keys instead. To migrate an existing token-enrolled deployment, see Migrating from enrollment tokens.

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"

MCP keys

ventstreamctl mcp keys generate --name <agent> mints an MCP access token and its hash locally for a keys file — it never contacts the control plane. See MCP server.

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.

​Install

​macOS and Linux

​Windows

​Verify a release

​Authenticate

​Profiles and context

​Organization context and environments

​Pipelines

​Lifecycle

​Managed configuration

​Deployments and agent keys

​Legacy: enrollment tokens

​Operations

​MCP keys

​Automation

Install

macOS and Linux

Windows

Verify a release

Authenticate

Profiles and context

Organization context and environments

Pipelines

Lifecycle

Managed configuration

Deployments and agent keys

Legacy: enrollment tokens

Operations

MCP keys

Automation