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

# CLI administration

> Install ventstreamctl and administer VentStream Cloud pipelines, agents, configuration, and operations.

`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.

<Note>
  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.
</Note>

## Install

`ventstreamctl` binaries are published in the
[VentStream releases repository](https://github.com/ventstream/ventstream-releases).

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

### macOS and Linux

Install the latest release:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/ventstream/ventstream-releases/releases/latest),
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](https://github.com/ventstream/ventstream-releases/blob/main/docs/verification.md).

The CLI requires a VentStream Cloud workspace, its control-plane URL, and an
authorized user account.

## Authenticate

Create an account at [ventstream.dev/signup](https://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:

```bash theme={null}
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](/docs/fleet/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:

```bash theme={null}
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:

```bash theme={null}
ventstreamctl orgs list
ventstreamctl config set-org <organization-id>
```

Then list and select an environment:

```bash theme={null}
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:

```bash theme={null}
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](https://ventstream.dev/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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
ventstreamctl pipelines configurations rollback orders-cdc <previous-revision> \
  --reason "rollback failed release" --wait
```

See [Managed configuration](/docs/fleet/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.

```bash theme={null}
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:

```bash theme={null}
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](/docs/deploy/kubernetes-managed-engine) for the complete
customer-side installation workflow.

Generate one short-lived, single-use enrollment grant:

```bash theme={null}
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:

```bash theme={null}
ventstreamctl agents status \
  --pipeline orders-cdc \
  --deployment <deployment-id>
```

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

```bash theme={null}
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](/docs/fleet/enrollment).

## Operations

List operation history for the selected environment or one pipeline:

```bash theme={null}
ventstreamctl operations list
ventstreamctl operations list --pipeline orders-cdc --status running
```

Inspect terminal results and delivery attempts:

```bash theme={null}
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.

```bash theme={null}
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.