CLI Reference

This page summarizes the WebTTY CLI surface. It is not a replacement for command help; use the CLI help as the source of truth for flags in your installed version.

rstream webtty --help
rstream webtty server --help
rstream webtty sessions --help

Workflow map

Start from the workflow you need, not from individual flags.

The common rule is that normal connection commands stay simple. For rstrm://..., the client uses engine inventory, WebTTY labels, and local trust stores before it reaches for managed metadata. Workspace-managed E2E uses the Control plane during client resolution because trusted device grants are workspace state; the WebTTY server does not call the Control plane during a terminal session. Users do not choose a key source on every connection.

Client commands

rstream webtty list lists online WebTTY servers discovered from live tunnel inventory:

rstream webtty list
rstream webtty list -q
rstream webtty list --filter 'labels.rstream.webtty.label.environment=prod' -o json

rstream webtty exec runs one command and exits. It defaults to JSON output because automation usually needs a structured result:

rstream webtty exec --url rstrm://shell -- whoami
rstream webtty exec --url rstrm://shell --output text -- hostname

rstream webtty client opens an interactive terminal:

rstream webtty client --url rstrm://shell

For a direct endpoint that is not resolved through rstream inventory, select a known server from the local trust store:

rstream webtty client --url ws://127.0.0.1:8080 --known-server shell

Both client and exec can pass command context:

rstream webtty exec \
  --url rstrm://shell \
  -e APP_ENV=prod \
  -w /srv/app \
  -u deploy \
  -- sh -lc 'pwd && id && printenv APP_ENV'

Use --tty, --no-tty, --interactive, and --no-interactive only when the default shape is not the one you need:

rstream webtty client --url rstrm://shell --tty --interactive
rstream webtty exec --url rstrm://shell --no-tty --no-interactive -- date

Server commands

Start a lightweight WebTTY tunnel through the active rstream project:

rstream webtty server -v --rstream --name shell

Keep the server private:

rstream webtty server -v --rstream --name shell --no-publish

Start a local validation server without rstream:

rstream webtty server -v --listen 127.0.0.1:8080 --allow-unauthenticated

Create, enroll, and start a registered server:

rstream webtty server create prod-shell --enroll
rstream webtty server -v --server-id <server-id>

If the server record is created from one machine and the WebTTY runtime runs on another, create first, then run the printed enrollment command on the runtime host:

rstream webtty server create prod-shell
rstream webtty server enroll <server-id>
rstream webtty server -v --server-id <server-id>

Use a runtime config file for service managers:

rstream webtty server -v --webtty-config /etc/rstream/webtty/prod-shell.yaml

--server-id, --server-enrollment, and --webtty-config are references to the same registered-server concept, not three different product concepts. --server-id <id> loads the default enrollment file for that server id. --server-enrollment <file> loads a specific enrollment file. --webtty-config <file> loads a runtime config that can include server.serverId or server.serverEnrollment plus operational settings.

--config is the global rstream CLI configuration file. --webtty-config is the WebTTY server runtime file. Keep those surfaces separate: the global config selects rstream account/project context, while the WebTTY runtime config describes one server process.

Runtime config

A runtime config keeps daemon commands short and reviewable:

version: 1
server:
  serverEnrollment: /etc/rstream/webtty/prod-shell.enrollment.yaml
  transport: websocket
  executionMode: login
  labels:
    environment: prod
    role: ops

Use the config for runtime shape. Do not put private keys or local server enrollment files in a shared config. Keep identity files in a directory with strict local permissions or use the host secret manager.

When the default enrollment directory is owned by the same service account that runs WebTTY, serverId can be used instead:

version: 1
server:
  serverId: srv_prod_shell_01
  transport: websocket
  executionMode: login

Both forms start the same registered server. The difference is operational ownership: serverId is concise, while serverEnrollment is explicit and easier to manage from configuration management.

Local file layout

WebTTY-local files live under the WebTTY directory:

~/.rstream/webtty/identities/<name>.identity.json
~/.rstream/webtty/enrollments/<server-id>.yaml
~/.rstream/webtty/known_servers.json

Workspace-managed trust lives under the workspace directory. This path exists only when the workspace uses Workspace Protection, which is an Enterprise workspace feature:

~/.rstream/workspaces/<workspace-id>/devices/<device-id>.json
~/.rstream/workspaces/<workspace-id>/webtty/identities/<device-id>.identity.json

The split matters. Workspace Protection is a platform-level feature. WebTTY uses it, but it is not owned by WebTTY.

Identities, authorized clients, and known servers

Create a local WebTTY endpoint identity. The same command is used for a server identity or for a client identity; the role comes from how the identity is used.

rstream webtty identity create --name shell
rstream webtty identity create --name operator-device

Show the public endpoint identity:

rstream webtty identity show --name shell --endpoint-identity

List and remove local WebTTY endpoint identities:

rstream webtty identity list
rstream webtty identity remove shell

Use the three trust commands in different places. identity manages local key material. authorized-client is the server-side allowlist of client public signing keys. known-server is the client-side pin for public server endpoint identities.

On the server side, authorize client endpoint identities once:

rstream webtty authorized-client add operator-device \
  --identity shell \
  --key '<client-endpoint-identity>'
rstream webtty authorized-client list --identity shell
rstream webtty authorized-client remove operator-device --identity shell

The server stores public client signing material in the authorized-client file for that server identity. The stored value is derived from the client endpoint identity:

signing_key_id:signing_public_key

Use --authorized-client-key, RSTREAM_WEBTTY_AUTHORIZED_CLIENT_KEYS, or --authorized-clients-file <file> when automation needs an explicit authorization source instead of the default file. Human-operated servers normally use authorized-client add/list/remove so public client keys can be managed without rewriting service commands.

For a registered explicit-key server, authorize clients by server id instead of local identity name:

rstream webtty authorized-client add operator-device \
  --server-id <server-id> \
  --key '<client-endpoint-identity>'

On the client side, register a known server endpoint identity once:

rstream webtty known-server add shell \
  --key '<server-endpoint-identity>' \
  --client-identity operator-device
rstream webtty known-server list
rstream webtty known-server remove shell

The server endpoint identity is public server material in this form:

encryption_key_id:encryption_public_key:signing_key_id:signing_public_key

Known-server endpoint identities are stored so clients can verify the server proof and encrypt a session key without passing --known-server-key on every invocation. --client-identity is optional, but it makes clients use the right local identity when the server requires a signed client proof. Known-server entries are not client authorization secrets. Client authorization is the server-side authorized-client store, workspace-managed device trust, or the surrounding tunnel/private transport policy.

When rstream ui opens an explicit-key WebTTY server, it uses the same local known-server association. If no known-server entry matches the target, rstream ui fails closed with a known-server add command instead of trusting the endpoint on first use. If the server is known but no client identity is associated, the interactive UI can ask which local identity to use. A remembered association is written only after the server identity has been verified and the session has opened. Non-interactive commands do not guess; they need an explicit identity source or a target-scoped known-server client_identity.

Use --known-servers-file <file> when automation needs a specific trust store instead of the default file.

Workspace device commands

Enroll the current machine as a trusted workspace device:

rstream workspace device enroll --kind cli --label operator-cli

Check local trust status:

rstream workspace device status

The default path uses the workspace attached to the active project context. If there is no active project context, or if the device is enrolled for a different workspace, list workspaces and pass the workspace explicitly:

rstream workspace list
rstream workspace device enroll --workspace <workspace-id> --kind cli --label operator-cli
rstream workspace device status --workspace <workspace-id>

When a registered server uses workspace-managed encryption, the client uses local workspace device trust during runtime resolution. The operator does not pass WebTTY recipient keys on each command.

The server side pins the public workspace keyset identity into its enrollment during workspace-managed server enrollment when the runtime host is already a trusted workspace device. If local trust material later changes, refresh the pin:

rstream webtty server trust <server-id>

The trust pin lets the WebTTY server verify workspace-managed client proofs against public workspace trust material without holding workspace private key material. It is a repair command, not a bypass for device trust.

Session commands

List managed sessions:

rstream webtty sessions list
rstream webtty sessions list --status active
rstream webtty sessions list --server-id <server-id>

Join as a spectator:

rstream webtty sessions join <session-id>

Join and request control:

rstream webtty sessions join <session-id> --tty --interactive --request-control --reason "Need to help"

Request and resolve control explicitly:

rstream webtty sessions request-control <session-id> --participant-id <participant-id> --reason "Need to help"
rstream webtty sessions control-requests <session-id>
rstream webtty sessions resolve-control <session-id> <request-id> --action grant
rstream webtty sessions resolve-control <session-id> <request-id> --action refuse

Export recordings:

rstream webtty sessions export <session-id> --format text --file session.log
rstream webtty sessions export <session-id> --format json --file session.json

Transports

The rstream CLI supports plain, websocket, and webtransport. Use the default unless your deployment has a concrete reason to select a transport.

rstream webtty server -v --transport websocket
rstream webtty client --url ws://127.0.0.1:8080 --transport websocket

The C++ WebTTY utilities support plain and websocket. WebTransport is intentionally Go-only.

Execution modes

spawn runs commands as child processes of the WebTTY server process. It is the default for lightweight WebTTY.

login uses a login-oriented execution path where the host supports it. It is the default for registered servers.

rstream webtty server -v --server-id <server-id> --execution-mode spawn
rstream webtty server -v --server-id <server-id> --execution-mode login --login-user deploy

Use --allow-client-user only when the server host accepts a user requested by the client.