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
`--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>

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)

Example:

rack-gateway login production https://gateway.example.com

logout

Revoke your session and remove local credentials.

rack-gateway logout [flags]

Flags:

--rack, -r - Logout from a specific rack (default: current rack)

Example:

rack-gateway logout
rack-gateway logout -r staging

test-auth

Test your authentication status.

rack-gateway test-auth [mfa|otp|webauthn]

Example:

rack-gateway test-auth
rack-gateway test-auth mfa
rack-gateway test-auth webauthn

Rack Management Commands

rack

Show current rack configuration.

rack-gateway rack

Output:

Current rack: production
URL: https://gateway.example.com
User: developer@company.com
Role: deployer

racks

List all configured racks.

rack-gateway racks

Output:

  RACK        URL                               USER
* production  https://gateway-prod.example.com  developer@company.com
  staging     https://gateway-staging.example.com  developer@company.com

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. They work the same as the native convox CLI commands.

apps

List applications.

rack-gateway apps

build

Create a new build.

rack-gateway build [flags]

Flags:

-a, --app - Application name
-d, --description - Build description
--manifest - Path to convox.yml (default: convox.yml)

Example:

rack-gateway build -a myapp -d "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
-d, --description - Deploy description
--manifest - Path to convox.yml

Example:

rack-gateway deploy -a myapp

env

Manage environment variables.

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

Subcommands:

rack-gateway env -a <app> - List environment variables
rack-gateway env set VAR=value -a <app> - Set a variable
rack-gateway env unset VAR -a <app> - Remove a variable

Example:

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

exec

Execute a command in a running process.

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

Example:

rack-gateway exec web "rails console" -a myapp
rack-gateway exec web 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 timestamp (e.g., 1h, 30m)
--filter - Filter logs by process type

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>

resources

List resources (databases, Redis, etc.).

rack-gateway resources

restart

Restart an application.

rack-gateway restart -a <app>

run

Run a one-off process.

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

Example:

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

scale

Scale application processes.

rack-gateway scale <process>=<count> -a <app> [flags]

Flags:

--cpu - CPU units
--memory - Memory in MB

Example:

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

Gateway-Specific Commands

api-token

Manage API tokens.

rack-gateway api-token [command]

Subcommands:

list - List API tokens (admin only)
get - Show a specific token
create - Create a new 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 deployer
rack-gateway api-token delete <token-id>

deploy-approval

Manage deploy approval requests.

rack-gateway deploy-approval [command]

Subcommands:

list - List pending approvals
approve - Approve a request
request - Create a new approval request
show - Show request details
wait - Wait for a request decision

Example:

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

gateway

Show gateway server information.

rack-gateway gateway

Output:

Gateway URL: https://gateway.example.com
Gateway Version: v0.1.0
Rack Alias: production

version

Show version information.

rack-gateway version

Output:

CLI version:     v0.1.0
Gateway version: v0.1.0
Rack version:    3.18.4

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=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