Skip to main content
This guide is for VentStream Cloud users who administer managed CDC and realtime pipelines with ventstreamctl. Authentication gives the CLI the same organization-scoped access as the VentStream Cloud dashboard.
The standalone VentStream engine does not require a Cloud account or ventstreamctl. Run it directly with local configuration when centralized administration is not needed. Engines authenticate to Cloud with per-deployment agent keys, not with the user credentials described here.
Create an account at ventstream.dev/signup, or accept an invitation from an existing organization, before starting CLI login.

​
Sign in from the CLI

The CLI targets the hosted VentStream Cloud control plane by default, so signing in needs no URL:
Self-hosted installations pass --control-plane <url> (or set it on the profile) to point at their own control plane. The CLI opens the VentStream authorization page in your system browser. Sign in with your existing account, complete any MFA or SSO checks your identity provider requires (enterprise OIDC), and approve the CLI session. The authorization flow uses PKCE, a one-time state value, and a loopback callback on 127.0.0.1. Your password is entered only in the browser and is never exposed to the CLI. The command also prints the authorization URL. Use --no-browser to suppress automatic launch and open that URL manually on the same workstation:
The browser callback expires after five minutes.

​
Select an organization and environment

After authentication, the CLI retrieves the organizations and environments that your account can access:
  • A single organization or environment is selected automatically.
  • Multiple choices produce an interactive numbered prompt.
  • An account with no organization remains authenticated until it accepts an invitation or creates an organization in the dashboard.
For a non-interactive terminal, or to select explicitly, pass a UUID, a unique UUID prefix (8+ characters), or the slug/name:
Change the saved context later without signing in again:

​
Enterprise SSO

When enterprise OIDC is enabled for a workspace, the same auth login command uses the configured identity provider. Depending on the provider configuration, VentStream either completes authorization in the browser or displays a device-code URL and code. An identity provider using a private PKI can be trusted with:

​
Check the session

Access tokens are short-lived. The CLI automatically refreshes an expiring token when the profile has a valid refresh session.
Print and immediately refresh the bearer token only when an integration requires it:
auth token prints a bearer credential. Never write its output to logs, shell-history expansions, or source-controlled files.

​
Account recovery

Use ventstream.dev/forgot-password to request a one-time reset link. A successful password reset revokes existing Cloud sessions. Run auth login again after setting the new password.

​
Log out

This revokes the selected first-party refresh session and removes the local profile. For an enterprise OIDC profile, it removes the local profile but does not end the identity-provider session. Use --all-sessions with a first-party profile to revoke every refresh session for the account. Add --keep-profile to retain non-secret control-plane and context defaults.

​
Profile storage

Profiles are stored at $XDG_CONFIG_HOME/ventstream/ventstreamctl.json or ~/.config/ventstream/ventstreamctl.json. The CLI atomically writes mode-0600 files on Unix-like systems and rejects symlinked or overly permissive profile files. Set VENTSTREAMCTL_CONFIG to use an isolated profile file in automation. See CLI administration for managed pipeline operations and scripting guidance.