Commands

Top-level commands and common workflows.

Written by uartnet

@uartnet

The CLI groups commands into a small number of operational areas: authentication, project and context management, tunnel operations, declarative management, signaling, remote terminals, and live inventory.

The root command is rstream. It accepts global flags that affect configuration loading and logging:

--config selects the CLI configuration file.
--context selects a data-plane context for commands that connect to the engine.
--api-url selects the hosted control-plane API URL.
-v or --verbose enables logs on stderr.
-l or --log-level sets debug, info, warn, error, or none.
-f or --log-format sets auto, json, json-pretty, text, or text-pretty.
--version prints version information.

Top-level command surface

The main operational commands are:

Command	Summary
`login`	Authenticate the CLI and store a token locally.
`logout`	Remove the stored token from the local configuration.
`project`	List projects and create a context from a project endpoint.
`context`	Create, update, select, and inspect local contexts.
`forward`	Create a tunnel and forward traffic to a local target.
`run`	Manage tunnels declaratively from YAML or Docker labels.
`tunnel`	List tunnels visible through the current engine and token.
`client`	List clients visible through the current engine and token.
`events`	Subscribe to the event stream over SSE or WebSocket.
`doctor`	Diagnose config, auth, context, project, DNS, TLS or QUIC transport, and engine state.
`ui`	Open the live terminal UI for WebTTY servers, tunnels, and clients.
`netcat`	Open TCP or rstream streams from the CLI.
`webtty`	Run or connect to a WebTTY server.

The shell completion and built-in help commands are omitted here. The exact subcommands and flags evolve over time, so the installed version should always be checked with the built-in help output.

Agent-friendly output

Automation should prefer JSON output where available:

rstream login -o json
rstream project list -o json
rstream project use <project-endpoint> --default -o json
rstream context list -o json
rstream context get <name> -o json
rstream context create <name> --engine <engine> --token-file <file> -o json
rstream tunnel list -o json
rstream client list -o json
rstream events --transport websocket -o json
rstream doctor -o json
rstream forward 8080 -o json

rstream doctor -o json is the readiness check to run after setup changes or while troubleshooting. It reports configuration, selected context, token claims, control-plane authentication, project resolution, DNS, TLS or QUIC transport, and engine inventory without printing token values.

Help and versioning

To inspect a command, use the --help flag:

rstream tunnel --help

To print the installed CLI version:

rstream --version

CLI Reference Configuration File