Skip to content
Rack Gateway

CLI Installation

The rack-gateway CLI is distributed as a single binary. Choose the installation method that works best for your platform.

Download from GitHub Releases (Linux x86_64)

Section titled “Download from GitHub Releases (Linux x86_64)”

Each release publishes a Linux x86_64 build with a checksum and a signed build provenance attestation:

Terminal window
VERSION=v0.1.10  # see https://github.com/docspring/rack-gateway/releases
curl -fsSLO https://github.com/docspring/rack-gateway/releases/download/$VERSION/rack-gateway-linux-amd64.tar.gz
curl -fsSLO https://github.com/docspring/rack-gateway/releases/download/$VERSION/rack-gateway-linux-amd64.tar.gz.sha256
sha256sum --check rack-gateway-linux-amd64.tar.gz.sha256
gh attestation verify rack-gateway-linux-amd64.tar.gz --repo DocSpring/rack-gateway
tar xzf rack-gateway-linux-amd64.tar.gz
sudo install -m 0755 rack-gateway-linux-amd64 /usr/local/bin/rack-gateway

The release build has no WebAuthn support (no CGO), so it verifies MFA with TOTP, YubiKey OTP or backup codes. To use a security key from the CLI, or on macOS and other platforms, build from source.

Verify Installation

Section titled “Verify Installation”
Terminal window
rack-gateway version

You should see output like:

client: v0.1.10
gateway: (not logged in)
server: (not logged in)

Shell Completion

Section titled “Shell Completion”

The CLI supports shell completion for bash, zsh, fish, and PowerShell.

Terminal window
# Add to ~/.bashrc
source <(rack-gateway completion bash)


# Or generate a file
rack-gateway completion bash > /etc/bash_completion.d/rack-gateway
Section titled “Recommended Alias”

Set up a short alias for convenience:

Terminal window
# Add to ~/.bashrc, ~/.zshrc, or equivalent
alias cg="rack-gateway"

Now you can use:

Terminal window
cg apps
cg deploy
cg logs -a myapp

WebAuthn Support (Optional)

Section titled “WebAuthn Support (Optional)”

Security keys (WebAuthn/FIDO2) in the CLI need a build with libfido2. Install it before building from source:

Terminal window
brew install libfido2

Building from Source

Section titled “Building from Source”

If you prefer to build from source:

  1. Prerequisites

  2. Clone and build

    Terminal window
    git clone https://github.com/docspring/rack-gateway.git
    cd rack-gateway
    task go:build:cli

  3. Install

    Terminal window
    sudo mv bin/rack-gateway /usr/local/bin/

Building with WebAuthn Support

Section titled “Building with WebAuthn Support”

To build with WebAuthn/FIDO2 support, use the default CLI build:

Terminal window
task go:build:cli

Building without WebAuthn

Section titled “Building without WebAuthn”

To build without WebAuthn support (smaller binary, no CGO):

Terminal window
task go:build:cli:nofido

Updating

Section titled “Updating”

To update, download the new release (Linux x86_64), or rebuild from source:

Terminal window
cd rack-gateway
git pull
task go:build:cli
sudo mv bin/rack-gateway /usr/local/bin/

Troubleshooting

Section titled “Troubleshooting”

“command not found”

Section titled ““command not found””

Make sure the binary is in your PATH:

/usr/local/bin/rack-gateway
which rack-gateway

If not, either move the binary to a directory in your PATH, or add its location:

Terminal window
export PATH="$PATH:/path/to/rack-gateway"

Permission denied

Section titled “Permission denied”

Make sure the binary is executable:

Terminal window
chmod +x /usr/local/bin/rack-gateway

macOS security warning

Section titled “macOS security warning”

On macOS, you may see a security warning the first time you run the CLI. Either:

  1. Right-click the binary in Finder and select “Open”, then click “Open” in the dialog
  2. Or run: xattr -d com.apple.quarantine /usr/local/bin/rack-gateway

Next Steps

Section titled “Next Steps”