Logo
Commands

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 an Engine API context for commands that connect to the engine.
  • --api-url selects the Control plane API URL.
  • --region selects an authorized region exposed by a managed Global project.
  • -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:

CommandSummary
loginAuthenticate the CLI and store a token locally.
logoutRemove the stored token from the local configuration.
projectManage projects, custom domains, reserved TCP addresses, and project contexts.
contextCreate, update, select, and inspect local contexts.
forwardCreate a tunnel and forward traffic to a local target.
runManage tunnels declaratively from YAML or Docker labels.
tunnelList tunnels visible through the current engine and token.
clientList clients visible through the current engine and token.
eventsSubscribe to the event stream over SSE or WebSocket.
doctorDiagnose config, auth, context, project, DNS, TLS or QUIC transport, and engine state.
uiOpen the live terminal UI for WebTTY servers, tunnels, and clients.
netcatOpen TCP or rstream streams and rstream datagram sessions from the CLI.
webttyRun 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.

Region selection applies to managed Global project contexts. The CLI resolves the selected region through the Control plane before connecting to the engine, rejects regions that are not exposed by the project, and rejects an explicit region for a regional project. Use rstream project list to inspect each project's ROUTING mode and REGIONS. An explicit --region cannot be combined with an explicit engine override.

Agent-friendly output

Automation should prefer JSON output where available:

rstream login -o json
rstream project list -o json
rstream project use <project-endpoint> -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 API authentication, project resolution, DNS, TLS or QUIC transport, and engine inventory without printing token values.

Project resources

Custom domains and reserved TCP addresses are Control plane resources. They can be managed without a live engine connection and default to the project selected by the current context. Pass --project-id to target another project.

Register a custom hostname, inspect the DNS records returned by the Control plane, verify it after DNS propagation, and remove it when it is no longer needed:

rstream project domain list
rstream project domain add api.example.com -o yaml
rstream project domain verify api.example.com -o yaml
rstream project domain remove api.example.com

Reserve, inspect, and release stable TCP addresses by public port:

rstream project tcp-address list
rstream project tcp-address reserve
rstream project tcp-address release <port>

Table output is the default. Use -o json or -o yaml when automation needs the complete resource, including DNS configuration and certificate state for a custom domain.

Help and versioning

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

rstream tunnel --help

To print the installed CLI version:

rstream --version
CLI ReferenceConfiguration File