CLI reference

The relay command-line interface — command groups, global flags, and where to go for each area.

The relay CLI manages every part of Relay from your terminal. See Install the CLI to get started.

This page summarizes the command surface. Full per-command reference is generated from the CLI itself and versioned per release.

Global flags

Available on every command:

Flag	Purpose
`--org`	Override the active organization (name or ID).
`--workspace`	Override the active workspace (name or ID).
`--profile`	Use a specific auth profile.
`--server`	gRPC server address (default from your credentials, or `api.userelay.sh:443`).
`--server-http`	HTTP server URL used for OAuth (default from your credentials, or `https://api.userelay.sh`).
`--insecure`	Use plaintext gRPC instead of TLS. For a local server without TLS only.
`--server-ca`	PEM CA bundle trusted for the server, added to the system roots (env `RELAY_SERVER_CA`).
`--server-cert` / `--server-key`	Client certificate and private key (PEM) for mTLS to the server (env `RELAY_SERVER_CERT`, `RELAY_SERVER_KEY`).
`--agent-tls`	Use TLS to the agent with the system roots. Implied by `--agent-ca` and `--agent-cert` (env `RELAY_AGENT_TLS`).
`--agent-ca`	PEM CA bundle trusted for agents; enables TLS to the agent (env `RELAY_AGENT_CA`).
`--agent-cert` / `--agent-key`	Client certificate and private key (PEM) for mTLS to the agent (env `RELAY_AGENT_CERT`, `RELAY_AGENT_KEY`).
`--agent-server-name`	TLS server name to verify on the agent certificate (env `RELAY_AGENT_SERVER_NAME`).
`--no-color`	Disable colored output.

Command groups

Auth & profiles

relay login [--sso --email you@company.com]   # authenticate
relay whoami                                   # show current user
relay logout                                   # sign out
relay profiles list|use|delete|current         # manage auth profiles

Organizations & workspaces

relay org list|create|use
relay ws list|create|use|delete
relay ws members list|add|remove|set-role|add-team|remove-team|set-team-role

Members, teams, roles & bindings

relay members list|invite|set-role|remove       # org members
relay teams list|create|delete|add-member|remove-member
relay roles list|create|update|delete           # custom roles
relay bindings list|create|delete                # grant roles to users/teams

See RBAC for the model.

Managed databases

relay db regions                                 # what you can provision into
relay db create <name> --engine ... --version ... --cloud ... --region ... --tier ... [--storage|--ha|--no-backups|--wait]
relay db list|get|status|nodes
relay db delete <id> [--delete-backups]

relay db is also available as relay database. relay db delete keeps the cluster's backups by default, matching the dashboard and API. Pass --delete-backups (the same as --keep-backups=false) to delete them too; that cannot be undone.

See Managed databases.

Connect & access

relay connect <name>...                          # open masked tunnels; Ctrl+C closes them
relay status                                     # open tunnels in the workspace
relay connections list|create|delete|update
relay connections agents set <connection> <agent>[:<priority>]...
relay connections groups list|create|delete|update|add-connection|remove-connection
relay credential-sources list|get|set|delete     # external secret sources
relay grants list|create|delete                   # access grants
relay runbook list|show|run|sync|history|result  # pre-approved runbooks

relay runbook run <name> -c <connection> --param k=v runs a runbook pinned to the version relay runbook show displays, and waits for its result (--json for scripts, --no-wait to queue it).

relay connections agents set replaces the agents that serve a connection. The agent with the highest priority becomes the connection's main agent, and an agent without a priority gets 0. relay connections create and relay connections update set the main agent with --agent. Several agents per connection, teams and enrollment tokens need CLI 0.9.0 or later. From CLI 0.8.0, relay connect dials the replica the server picks for each tunnel.

See Access & governance.

Agents

relay agents list                                # NAME TYPE STATUS REPLICAS VERSION; -o wide for more
relay agents get <agent>                         # the agent's replicas
relay agents create <name> [--managed] [--min-replicas N --max-replicas N] [--expected-replicas N] [--description D]
relay agents update <agent> [--min-replicas N --max-replicas N] [--expected-replicas N] [--description D]
relay agents delete <agent>
relay agents teams set <agent> [<team>...]       # restrict an agent to teams; no teams = unrestricted
relay agents replicas delete <agent> <replica>
relay enrollment-tokens create --name <name> --agent <agent> [--expires-in D] [--single-use]
relay enrollment-tokens list|delete

--managed creates an agent whose replicas Relay runs. --min-replicas and --max-replicas go from 1 to 50 and apply only to managed agents. --expected-replicas (1 to 50, 0 clears it) sets how many replicas a self-hosted agent should run. --agent binds an enrollment token to a self-hosted agent and is required.

The CLI used to call an agent a pool. relay agents pools …, relay connections pools set and the --pool flags still work as hidden aliases for now, and print the new command to use.

See Agents.

Audit

relay audit-logs                                 # list control-plane audit logs

Version, completion & license

relay version                                    # print the CLI version
relay completion bash|zsh|fish|powershell        # generate a shell completion script
relay license status [-o json]                   # license state, limits and usage (Agent Edition)

relay license applies to self-hosted Agent Edition installations.

On this page