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:

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

The * indicates 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
# Output: Current rack: staging (https://gateway-staging.example.com)

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.

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": "rgw_sess_abc123...",
      "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": "rgw_sess_def456...",
      "email": "developer@company.com",
      "expires_at": "2024-02-15T10:30:00Z",
      "session_id": 2048,
      "channel": "cli"
    }
  }
}

Removing a Rack

Section titled “Removing a Rack”

To remove a rack configuration, log out from it:

Terminal window
# Logout from staging (removes session but keeps config)
rack-gateway logout -r staging

To completely remove a rack, edit the config file directly or log in again with the same alias to replace 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 API tokens with RACK_GATEWAY_API_TOKEN instead of managing OAuth sessions:

Terminal window
# In your CI environment
export RACK_GATEWAY_API_TOKEN="rgw_token_..."
export RACK_GATEWAY_RACK="production"


rack-gateway deploy

Precedence Order

Section titled “Precedence Order”

When determining which rack to use:

  1. --rack flag (highest priority)
  2. RACK_GATEWAY_RACK environment variable
  3. current in config file (default)

Troubleshooting

Section titled “Troubleshooting”

”Rack not found”

Section titled “”Rack not found””
Error: rack "production" not found

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. Re-login to the affected rack:

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

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:

Terminal window
rack-gateway racks
#   RACK        URL                             USER
# * production  https://gateway-prod.example.com  admin@company.com
#   staging     https://gateway-staging.example.com  developer@company.com

Next Steps

Section titled “Next Steps”