Skip to content
Rack Gateway

Multi-Rack Configuration

The rack-gateway CLI supports connecting to multiple gateways, making it easy to work with different environments (production, staging, development) from a single machine.

Adding Racks

Section titled “Adding Racks”

Each time you run login, you add a new rack configuration:

Terminal window
# Add production rack
rack-gateway login production https://gateway-prod.example.com


# Add staging rack
rack-gateway login staging https://gateway-staging.example.com


# Add EU production rack
rack-gateway login eu-prod https://gateway-eu.example.com

The first argument (production, staging, etc.) is an alias you choose. Use short, memorable names.

Listing Racks

Section titled “Listing Racks”

View all configured racks:

Terminal window
rack-gateway racks

Output:

Configured racks:
* production
  staging
  eu-prod

The * marks the current rack.

Switching Racks

Section titled “Switching Racks”

Change the default rack:

Terminal window
# Switch to staging
rack-gateway switch staging


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

Per-Command Rack Override

Section titled “Per-Command Rack Override”

Use --rack (or -r) to run a single command against a different rack:

Terminal window
# List apps on production while staging is current
rack-gateway apps --rack production


# Deploy to staging
rack-gateway deploy -r staging


# Check logs on EU production
rack-gateway logs -a myapp -r eu-prod

The --rack flag doesn’t change your default; it only affects that one command. Deploy approval commands also take a comma-separated list of racks, or all.

Environment Variable Override

Section titled “Environment Variable Override”

Set RACK_GATEWAY_RACK to override the current rack:

Terminal window
# Use staging for all commands in this shell
export RACK_GATEWAY_RACK=staging
rack-gateway apps  # Uses staging


# Or for a single command
RACK_GATEWAY_RACK=production rack-gateway apps

Configuration File Structure

Section titled “Configuration File Structure”

Your rack configurations are stored in ~/.config/rack-gateway/config.json:

{
  "current": "production",
  "gateways": {
    "production": {
      "url": "https://gateway-prod.example.com",
      "token": "Fz2kQ...",
      "email": "developer@company.com",
      "expires_at": "2024-02-15T10:30:00Z",
      "session_id": 1024,
      "channel": "cli",
      "device_id": "8f4c4b8c-...",
      "device_name": "dev-mbp",
      "mfa_verified": true
    },
    "staging": {
      "url": "https://gateway-staging.example.com",
      "token": "pR7wD...",
      "email": "developer@company.com",
      "expires_at": "2024-02-15T10:30:00Z",
      "session_id": 2048,
      "channel": "cli"
    }
  }
}

Removing a Rack

Section titled “Removing a Rack”

logout ends your session on that rack’s gateway, then removes the rack, with its URL and session token, from your config:

Terminal window
rack-gateway logout -r staging

If the gateway is gone for good, rack-gateway logout -r staging --local removes the rack without contacting it.

Updating a Gateway URL

Section titled “Updating a Gateway URL”

If a gateway URL changes, simply log in again with the same alias:

Terminal window
# Gateway moved to new URL
rack-gateway login production https://new-gateway.example.com
# Replaces the old production configuration

Best Practices

Section titled “Best Practices”

Naming Conventions

Section titled “Naming Conventions”

Use consistent, descriptive aliases:

Terminal window
# Good: Clear environment names
rack-gateway login prod https://gateway-prod.example.com
rack-gateway login staging https://gateway-staging.example.com
rack-gateway login dev https://gateway-dev.example.com


# Good: Region-based for multi-region
rack-gateway login us-prod https://gateway-us.example.com
rack-gateway login eu-prod https://gateway-eu.example.com


# Avoid: Ambiguous names
rack-gateway login rack1 https://...  # Which environment is this?

Shell Aliases for Common Racks

Section titled “Shell Aliases for Common Racks”

Create aliases for frequently used rack combinations:

Terminal window
# In ~/.bashrc or ~/.zshrc
alias cgp="rack-gateway --rack production"
alias cgs="rack-gateway --rack staging"


# Usage
cgp apps      # Production apps
cgs deploy    # Deploy to staging

CI/CD Configuration

Section titled “CI/CD Configuration”

For CI/CD, use an API token instead of a login. CI has no config file, so give it the gateway URL too:

Terminal window
# In your CI environment
export RACK_GATEWAY_API_TOKEN="rgw_..."
export RACK_GATEWAY_URL="https://gateway-prod.example.com"


rack-gateway deploy --app myapp --wait

Precedence Order

Section titled “Precedence Order”

When determining which rack to use:

  1. --rack flag (highest priority)
  2. RACK_GATEWAY_RACK environment variable
  3. RACK_GATEWAY_URL (an unnamed rack, used with RACK_GATEWAY_API_TOKEN)
  4. current in config file (default)

Troubleshooting

Section titled “Troubleshooting”

“Rack not found”

Section titled ““Rack not found””
Error: rack production not found. Use 'rack-gateway racks' to list available racks

The alias doesn’t exist in your config. List available racks:

Terminal window
rack-gateway racks

“Session expired” on one rack

Section titled ““Session expired” on one rack”

Sessions expire independently per rack. Sign in to the affected rack again (its URL is kept):

Terminal window
rack-gateway login production

Different users on different racks

Section titled “Different users on different racks”

It’s normal to have different users or roles on different racks. Each rack maintains its own session:

rack-gateway rack shows who you’re logged in as on the current rack; rack-gateway rack -r staging shows your login on staging.

Next Steps

Section titled “Next Steps”