Reference · Version 2.4.1

CLI Reference

The relay command line tool lets you create, inspect, and manage relays, tunnels, and deployments from your terminal. Every subcommand accepts --help for a short summary.

Synopsis

relay [global options] <command> [command options] [arguments]

Global options

Flag	Default	Description
`-c, --config PATH`	`~/.relay/config.toml`	Path to the configuration file.
`-p, --profile NAME`	`default`	Named profile to use from the config file.
`-o, --output FORMAT`	`table`	Output format: `table`, `json`, or `yaml`.
`-v, --verbose`	off	Print request and response details to stderr.
`--no-color`	off	Disable colored output. Also honored via `NO_COLOR`.
`-h, --help`		Show help for the current command.
`--version`		Print the installed version and exit.

Commands

relay login

Authenticate with your account. Opens a browser window unless --token is supplied.

relay login
relay login --token $RELAY_TOKEN

relay tunnel

Expose a local port on a public URL.

relay tunnel 3000
relay tunnel 8080 --subdomain my-app --region eu-west

Option	Description
`--subdomain NAME`	Request a specific subdomain. Must be unique across your account.
`--region REGION`	Edge region to connect through. Run `relay regions` to list options.
`--auth USER:PASS`	Require HTTP basic auth in front of the tunnel.
`--ttl DURATION`	Close the tunnel automatically after a duration such as `30m` or `4h`.

relay deploy

Build and deploy the project in the current directory.

relay deploy
relay deploy --env staging --wait

Tip: relay deploy --wait blocks until the new version passes health checks, and exits with a non-zero status if it fails. Useful in CI.

relay logs

Stream logs from a deployment.

relay logs --follow
relay logs --since 2h --grep "ERROR"

relay env

Manage environment variables for a deployment.

relay env list
relay env set DATABASE_URL="postgres://..."
relay env unset DEBUG

Exit codes

Code	Meaning
`0`	Success.
`1`	General error. Details are written to stderr.
`2`	Invalid usage, such as an unknown flag.
`3`	Authentication required or token expired.
`4`	Resource not found.

Shell completion

Generate a completion script for your shell:

relay completion bash > /etc/bash_completion.d/relay
relay completion zsh > "${fpath[1]}/_relay"
relay completion fish > ~/.config/fish/completions/relay.fish