CLI Workflow

The rstream CLI can operate in two main modes.

The first mode is interactive and account-wide: authenticate with rstream login, then select a project and open tunnels. This mode is convenient on developer machines because it keeps the local configuration small and makes it easy to switch between projects.

The second mode is project-scoped: create or use a context that already contains an engine endpoint and a token scoped to a single project. This mode is a better fit for servers, CI, and devices because it avoids account-wide credentials and makes the runtime configuration explicit and auditable.

Projects and contexts

A project groups tunnels, credentials, and access controls in the hosted platform. The CLI selects a project by writing a local context that contains the project endpoint and the associated engine endpoint.

A context is a local configuration entry that defines how the CLI connects to rstream. In practice a context contains a name, an API URL, a project endpoint, an engine address, authentication storage, and optional transport settings such as DNS override, local bind configuration, QUIC transport selection, or proxy settings. Contexts can be selected explicitly with --context or set as the default context.

Hosted control plane and engine data plane

In the hosted platform, the Dashboard and its APIs act as the control plane. This is where projects and credentials are managed, and where the CLI resolves a project endpoint into an engine endpoint.

The engine is the data plane entrypoint. It hosts tunnel endpoints, enforces access policies, authenticates inbound requests, and relays traffic to upstream services. In self-hosted deployments, the workflow typically targets the engine directly and does not rely on the hosted control plane.

Running without login or config files

The CLI can run without a prior login and without pre-existing contexts when the engine endpoint and token are provided through environment variables.

RSTREAM_ENGINE="<project-endpoint>.<cluster-host>:443" \
RSTREAM_AUTHENTICATION_TOKEN="<token>" \
rstream forward 8080

This pattern is useful for containers, CI jobs, and single-purpose agents. If several commands need to share the same target project, a named context is usually easier to inspect and rotate.

Readiness checks

Run rstream doctor -o json after setup changes or when troubleshooting. It checks the selected config, context, token claims, hosted control-plane authentication, project resolution, engine address, DNS, TLS or QUIC transport, and live engine inventory. The command is designed for agents and CI because it returns structured status without printing secrets.

Token handling and operational safety

An authentication token is a private secret. If a token is leaked, it should be treated as a credential compromise and revoked or rotated as soon as possible.

In the hosted platform, tokens and application credentials can be revoked from the Dashboard. Short-lived tokens generated from application credentials can be renewed continuously and should be preferred for untrusted clients and devices.