CLI Commands

Gordon provides a command-line interface for server management, deployment, and authentication.

Most list commands also support --json for machine-readable output.

Commands are organized by where they run:

• Server Commands - Must run on the machine hosting Gordon
• Management Commands - Work locally or remotely
• Client Commands - CLI utilities that don't require a running Gordon server

Server Commands (local only)

Management Commands (local or remote)

Management commands run locally through in-process services by default. Add --remote to target another Gordon instance.

Client Commands

Quick Reference

# Start Gordon
gordon serve
gordon serve --config /path/to/config.toml

# Reload configuration
gordon reload

# Deploy a specific route
gordon deploy myapp.example.com

# Restart a running container
gordon restart myapp.example.com

# First-time route setup
gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production

# Then push and deploy
gordon push app.example.com --build --no-confirm

# Push an image and deploy
gordon push myapp.example.com --build

# Push and deploy without confirmation
gordon push myapp.example.com --no-confirm

# Roll back to a previous tag
gordon rollback myapp.example.com

# View logs
gordon logs                          # Gordon process logs
gordon logs -f                       # Follow process logs
gordon logs -n 100                   # Last 100 lines
gordon logs myapp.local              # Container logs for myapp.local
gordon logs myapp.local -f           # Follow container logs

# Check version
gordon version

# Backups
gordon backups list
gordon backups run app.example.com
gordon backups detect app.example.com
gordon backups status

# Images
gordon images list
gordon images prune --runtime-only
gordon images prune --keep 3

# Authentication
gordon auth login --remote https://gordon.example.com --token $TOKEN
gordon auth status
gordon auth show-token
gordon auth logout
gordon auth token generate --subject ci-bot --expiry 0
gordon auth token list
gordon auth token revoke <token-id>
gordon auth internal

# Routes
gordon routes list
gordon routes add myapp.example.com myapp:latest
gordon routes remove myapp.example.com
gordon routes deploy myapp.example.com

# Attachments
gordon attachments list
gordon attachments add app.example.com postgres:18
gordon attachments remove app.example.com postgres:18

# Secrets
gordon secrets list myapp.local
gordon secrets set myapp.local DATABASE_URL "postgres://..."
gordon secrets remove myapp.local DATABASE_URL

# Remotes
gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
gordon remotes list
gordon remotes use prod

# Preview environments
gordon preview create app.example.com --branch feature-x
gordon preview list
gordon preview extend app.example.com --branch feature-x
gordon preview delete app.example.com --branch feature-x

# Volumes
gordon volumes list
gordon volumes prune

# Auto-route allowlist
gordon autoroute allow list
gordon autoroute allow add example.com
gordon autoroute allow add "*.staging.example.com"
gordon autoroute allow remove example.com

Global Options

Remote Targeting

The CLI can target remote Gordon instances using client config, an active remote, --remote, or GORDON_REMOTE environment variable. Use --remote and --token as global overrides when you want to bypass your saved configuration.

Important: The remote URL must be the gordon_domain configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.

Use --insecure when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate. You can make this persistent with insecure_tls = true in [client] of ~/.config/gordon/gordon.toml or in a specific entry in ~/.config/gordon/remotes.toml. For Tailscale setups, you can also avoid --insecure by using the machine *.ts.net name with Tailscale-issued TLS certs in Gordon server config. Your public app domains can still use wildcard DNS and normal reverse-proxy routing.

# Using flags (use the gordon_domain from remote Gordon config)
gordon routes list --remote https://gordon.example.com --token $TOKEN

# Against self-signed/private CA endpoint
gordon --remote https://gordon.example.com --token $TOKEN --insecure status

# Using environment variables
export GORDON_REMOTE=https://gordon.example.com
export GORDON_TOKEN=$TOKEN
export GORDON_INSECURE=true
gordon routes list

Exit Codes

Environment Variables

Gordon reads configuration from environment variables:

GORDON_SERVER_PORT=8080 gordon serve
GORDON_LOGGING_LEVEL=debug gordon serve

Pattern: GORDON_SECTION_KEY (uppercase, underscores)

Related

• Core Concepts
• Configuration Reference