CLI Commands

This page documents all available commands in the rack-gateway CLI.

Global Flags

These flags work with any command:

Flag	Short	Description
`--rack`	`-r`	Override the current rack (deploy approval commands accept a comma-separated list, or `all`)
`--config`		Override config directory
`--api-token`		Use API token for authentication
`--mfa-code`		Provide MFA code for step-up auth
`--mfa-method`		Specify MFA method (totp/webauthn)
`--help`	`-h`	Show help for a command

Authentication Commands

Authenticate with a gateway via OAuth.

rack-gateway login [rack-alias] [gateway-url] [flags]

Arguments:

rack-alias - A name you choose for this rack (e.g., production, staging)
gateway-url - The gateway’s URL (e.g., https://gateway.example.com)

With no arguments it signs in again to the current rack; with only a rack alias, to that configured rack.

Flags:

--no-open - Print the login URL instead of opening a browser
--auth-file - Also write the login URL to a file, for automation

Example:

rack-gateway login production https://gateway.example.com
rack-gateway login            # sign in again to the current rack

logout

End the rack’s session on the gateway, then remove the rack, with its URL and session token, from your local config. If the gateway can’t be reached or doesn’t end the session, the rack stays configured and the command fails.

rack-gateway logout [flags]

Flags:

--local - Only remove the rack from this machine. The session stays valid on the gateway until it expires or you revoke it under your sessions in the web UI.

Use the global --rack flag to log out of another rack.

Example:

rack-gateway logout
rack-gateway logout -r staging

test-auth

Test your authentication status.

rack-gateway test-auth [mfa]

Example:

rack-gateway test-auth                            # Test the session (or RACK_GATEWAY_API_TOKEN)
rack-gateway test-auth mfa                        # Also verify your preferred MFA method
rack-gateway test-auth mfa --mfa-method webauthn  # Verify a specific method

Rack Management Commands

rack

Show the current rack (or the one --rack or RACK_GATEWAY_RACK selects) and your login. Its subcommands (info, logs, params, ps, releases, scale, update) act on the rack itself.

rack-gateway rack

Output:

Current rack: production
Gateway URL: https://gateway.example.com
Status: Logged in as developer@company.com
Token expires: 2026-12-01T10:00:00Z

racks

List all configured racks.

rack-gateway racks

Output:

Configured racks:
* production
  staging

switch

Switch to a different rack.

rack-gateway switch <rack-alias>

Example:

rack-gateway switch staging

Convox Commands

These commands are proxied to the Convox rack API and work the same as the native convox CLI commands. The CLI only has commands for the rack API routes the gateway forwards (see Permissions), so Convox commands such as certs, registries, resources, instances keyroll, instances terminate and apps cancel aren’t available.

Commands that take -a, --app find the app from the flag, then CONVOX_APP, then a .convox/app file in the current directory or a parent, then the current directory’s name.

apps

List applications.

rack-gateway apps

build

Create a new build.

rack-gateway build [flags]

Flags:

-a, --app - Application name
--description - Build description
-m, --manifest - Path to the manifest (default: convox.yml)
-f, --file - Path to the Dockerfile
--no-cache - Build without the cache

Example:

rack-gateway build -a myapp --description "Deploy v1.2.3"

builds

List builds for an application.

rack-gateway builds -a <app>

deploy

Deploy an application (build + promote).

rack-gateway deploy [flags]

Flags:

-a, --app - Application name
--description - Build description
-m, --manifest - Path to the manifest
-f, --file - Path to the Dockerfile
--no-cache - Build without the cache
--wait - Wait for the deployment to finish

Example:

rack-gateway deploy -a myapp --wait

env

Manage environment variables.

rack-gateway env [command] -a <app>

Subcommands:

rack-gateway env -a <app> - List environment variables (secret and protected values, and values with credentials in them, masked)
rack-gateway env get VAR -a <app> - Show one variable. --unmask shows a secret value (needs convox:secret:read and a step-up)
rack-gateway env set VAR=value -a <app> - Set variables
rack-gateway env unset VAR -a <app> - Remove variables
rack-gateway env edit -a <app> - Edit the variables in $EDITOR

Flags (set, unset and edit):

--promote - Promote the new release
--allow-protected - Change or remove the protected env vars named in the command (admins only, see below)

Example:

rack-gateway env -a myapp
rack-gateway env set DATABASE_URL=postgres://... -a myapp
rack-gateway env unset DEBUG -a myapp --promote

Protected env vars

An app’s protected env vars (set under Apps → {app} → Settings) are masked everywhere and can’t be changed or removed by accident: env set and env unset refuse them. To rotate or remove one without unprotecting it, an admin names it in the command and passes --allow-protected:

rack-gateway env set DATABASE_URL=postgres://new-host/db --allow-protected -a myapp
rack-gateway env unset LEGACY_API_URL --allow-protected -a myapp

Only users holding convox:env:set_protected (admins) can do this. API tokens never can, whatever their permissions, because they can’t complete MFA.
Every such command asks for MFA (one code or key touch), even within the step-up window, and the gateway verifies it on the request that changes the protected key.
Before MFA the CLI prints each key it changes with the app and rack (for example On app myapp (rack production): set env var DATABASE_URL). The macOS PIN dialog lists the same lines, and the key touch prompt and notification name the app and rack. Values are never shown. A key that isn’t an env var name is refused before MFA.
Without a terminal (scripts, AI agents) --allow-protected needs an explicit -a/--app, so the command line in the PIN dialog names the app being changed. The dialog quotes any argument that contains spaces or unusual characters, so one argument can’t pass for several.
Only the keys named on the command line are unlocked. Other protected keys stay as they are.
The gateway writes one audit log entry per protected key changed (env.set_protected or env.unset_protected) and never logs the values.
The web UI’s env editor still refuses protected keys.
Changing the list of protected (or secret) env vars also needs MFA on that request, even within the step-up window. Otherwise a key could be unprotected, changed and protected again with one step-up.

exec

Execute a command in a running process.

rack-gateway exec <process-id> <command> -a <app>

Example:

rack-gateway ps -a myapp                      # find the process ID
rack-gateway exec web-6f8b9c-x2kq4 bash -a myapp

logs

View application logs.

rack-gateway logs -a <app> [flags]

Flags:

-f, --follow - Stream logs in real-time
--since - Show logs since a time or duration (e.g., 1h, 30m)
--filter - Only show lines matching this filter

Example:

rack-gateway logs -a myapp -f
rack-gateway logs -a myapp --since 1h --filter web

ps

List application processes.

rack-gateway ps -a <app>

releases

List releases for an application.

rack-gateway releases -a <app>

restart

Restart an application.

rack-gateway restart -a <app>

run

Run a one-off process.

rack-gateway run <service> <command> -a <app>

Flags:

-d, --detach - Don’t attach to the process
--release - Run a specific release
--env - Extra environment variables
--entrypoint - Override the entrypoint

Example:

rack-gateway run web "rake db:migrate" -a myapp

scale

Scale application processes.

rack-gateway scale <service> -a <app> [flags]

Flags:

--count - Number of processes
--cpu - CPU units
--memory - Memory in MB

Example:

rack-gateway scale web --count 3 -a myapp
rack-gateway scale worker --count 2 --memory 512 -a myapp

Gateway-Specific Commands

api-token

Manage API tokens.

rack-gateway api-token [command]

Subcommands:

list - List your API tokens (admins see everyone’s)
get - Show a specific token
create - Create a new token (--name, --role or --permission, --expires-at, --user for admins, --output text|json|token)
delete - Delete a token

Example:

rack-gateway api-token list
rack-gateway api-token get <token-id>
rack-gateway api-token create --name "CI/CD" --role cicd
rack-gateway api-token delete <token-id>

deploy-approval

Manage deploy approval requests.

rack-gateway deploy-approval [command]

Subcommands:

list - List requests (--open for pending only, --status, --app, --commit)
approve - Approve a request, by ID or by app and commit
request - Create a new approval request (--wait blocks until it’s decided)
show - Show request details
wait - Wait for requests for a commit to appear, and show (or with --approve, approve) them

Example:

rack-gateway deploy-approval list
rack-gateway deploy-approval approve <request-id>
rack-gateway deploy-approval approve --app web,proxy --commit <sha> --rack us,eu
rack-gateway deploy-approval show <request-id>
rack-gateway deploy-approval request --app myapp --git-commit <sha> --message "Deploy"
rack-gateway deploy-approval wait --commit <sha> --approve

See Deploy Approvals for the full workflow.

gateway

Show gateway server information.

rack-gateway gateway

Output:

Gateway URL:     https://gateway.example.com
Gateway Version: v0.1.10

Rack Name:       production
Rack Alias:      production
Rack Host:       https://api.production-system.svc.cluster.local:5443

Logged in as:    developer@company.com
Name:            Developer
Roles:           deployer

version

Show version information.

rack-gateway version

Output:

client: v0.1.10
gateway: v0.1.10
server: 3.23.3

web

Open the gateway web UI in your browser.

rack-gateway web

completion

Generate shell completion scripts.

rack-gateway completion <shell>

Supported shells: bash, zsh, fish, powershell

Example:

rack-gateway completion bash > /etc/bash_completion.d/rack-gateway
source <(rack-gateway completion zsh)

Examples

Common Workflows

Deploy to production:

rack-gateway deploy -a myapp -r production

Check logs across environments:

rack-gateway logs -a myapp -r staging --since 1h
rack-gateway logs -a myapp -r production -f

Scale for high traffic:

rack-gateway scale web --count 5 -a myapp -r production

Run migrations:

rack-gateway run web "rake db:migrate" -a myapp -r production

Emergency rollback:

rack-gateway releases -a myapp -r production
# Note the previous release ID
rack-gateway releases rollback <release-id> -a myapp -r production

Getting Help

For any command, add --help to see available options:

rack-gateway --help
rack-gateway deploy --help
rack-gateway env --help