CLI Reference

The outray package provides tunnel clients, browser authentication, and Secrets commands. It does not start your local application or install an observability SDK.

Commands

version and -v are version aliases; help and -h are help aliases. validate is an alias for validate-config.

Tunnel flags

Local ports must be between 1 and 65535. Direct tunnel commands forward to localhost.

outray 3000 --subdomain preview
outray http 8080 --domain api.example.com
outray tcp 5432 --remote-port 25432
outray udp 5000 --remote-port 35000
outray 3000 --key "$OUTRAY_API_KEY"
outray 3000 --local-only --subdomain preview

The single-tunnel CLI reads --key, not OUTRAY_API_KEY automatically. API tokens belong to their issuing organization; --org does not change a token's scope.

Read TCP & UDP tunnels for endpoint and port behavior and Password protection for its security boundaries.

Configuration files

Both start and validate-config default to outray/config.toml relative to the current working directory:

outray validate-config
outray start
outray validate-config --config ./outray/team.toml
outray start --config ./outray/team.toml

Only the supported fields below are accepted. Values are literal TOML; environment-variable interpolation is not performed.

[global]
org = "my-team"

[tunnel.web]
protocol = "http"
local_port = 3000
subdomain = "my-app"

[tunnel.api]
protocol = "http"
local_port = 8000
custom_domain = "api.example.com"

[tunnel.database]
protocol = "tcp"
local_port = 5432
local_host = "localhost"
remote_port = 25432

[tunnel.game]
protocol = "udp"
local_port = 5000
remote_port = 35000

[secrets]
org = "my-team"
vault = "my-app"
environment = "development"

Global fields

Tunnel fields

The current HTTP client always forwards to localhost, including when local_host appears in TOML. Use local_host for TCP or UDP targets.

outray start requires a saved browser login and at least one tunnel. Direct-command flags such as --key, --no-logs, and --qr are not applied by start. To change tunnel behavior, use the fields supported by the config parser.

The [secrets] section is target metadata for Secrets commands; start does not automatically inject those values into applications.

Secrets commands

Create a vault and environment in the console before targeting them from the CLI. Run outray secrets --help for local help.

Target and authentication

outray secrets use --org my-team --vault my-app --env development
outray secrets list
outray secrets run -- npm run dev

Use --org/-o, --vault/-v, and --env/-e to choose a target. --config <path> selects an explicit TOML file; otherwise the CLI searches ancestor directories for the nearest outray/config.toml.

Target precedence is explicit flags, then environment variables, then config. For the organization, [global].org and the active browser-login organization are additional fallbacks.

Authentication tries OUTRAY_TOKEN, then OUTRAY_API_KEY, then saved browser login. A token needs the appropriate secrets:read, secrets:write, or secrets:delete permission and must allow the target vault/environment.

--project/-p, OUTRAY_SECRETS_PROJECT, and [secrets].project are retained compatibility aliases for vault selection; prefer vault.

Export and set values

outray secrets pull --format json
outray secrets pull --out .env.local
outray secrets set DATABASE_URL
outray secrets set DATABASE_URL --value-stdin < private-database-url.txt
outray secrets import --from .env.local

pull accepts --format env|json, --out <path>, and --force. Without --out, values go to stdout. File exports do not overwrite an existing file unless --force is provided.

set does not accept a secret value as a positional argument. Use its hidden prompt or --value-stdin (--stdin is an alias). A single trailing newline is stripped from stdin input. import --from - reads a dotenv document from stdin.

Exported files contain plaintext secrets. Keep them out of version control, logs, and build artifacts.

Delete, rollback, and production

delete and rollback require an interactive confirmation, or an explicit --yes in automation. Rollback version numbers must be positive integers.

For environments named prod or production, commands that reveal values, inject values, or mutate secrets also require --confirm-production. This does not bypass token scopes or resource restrictions.

Watch mode

outray secrets run --watch --watch-interval 5 -- npm run dev

Watch mode polls for changes and restarts the child process when values change. The default interval is 5 seconds; --watch-interval must be at least 1 second. A temporary connection failure leaves the existing child running, while loss of access stops it.

Remote values override matching inherited environment variables. The CLI removes OUTRAY_TOKEN and OUTRAY_API_KEY from the child environment, including values supplied under those names. Use a separate key such as OBSERVABILITY_TOKEN and pass it as the SDK's apiKey when combining Secrets injection with observability.

There are no CLI commands here for creating vaults, creating environments, or listing historical versions. Use the Secrets console for those workflows.

Environment variables

--dev also selects the CLI's development environment. The default development endpoints are ws://localhost:3547 and http://localhost:6767, and login is stored separately in ~/.outray/config.dev.json. Do not use --dev simply because you are tunneling a development application; it is for a local OutRay installation.

Secrets commands additionally accept --api-url <url> to override their API base. SDKs and framework plugins have their own environment variables; see their individual guides.