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)
| Command |
Description |
Documentation |
gordon serve |
Start the Gordon server |
serve |
gordon auth |
Manage Gordon server authentication |
auth |
gordon ca |
Manage the internal Certificate Authority |
ca |
Management Commands (local or remote)
Management commands run locally through in-process services by default. Add --remote to target another Gordon instance.
| Command |
Description |
Documentation |
gordon attachments |
Manage container attachments |
attachments |
gordon autoroute |
Manage auto-route domain allowlist |
autoroute |
gordon backups |
Manage database backups |
backup |
gordon bootstrap |
Configure a route, attachments, and secrets for an app |
bootstrap |
gordon config show |
Show server configuration |
config |
gordon deploy |
Manually deploy or redeploy a route |
serve |
gordon images |
List and prune images |
images |
gordon logs |
Display Gordon process or container logs |
serve |
gordon networks list |
List Gordon-managed Docker networks |
networks |
gordon preview |
Create or manage preview environments |
preview |
gordon push |
Tag, push, and optionally deploy an image |
push |
gordon attachments push |
Build/push attachment images to registry |
attachments |
gordon reload |
Reload configuration and sync containers |
serve |
gordon restart |
Restart a running container |
restart |
gordon rollback |
Roll back to a previous image version |
rollback |
gordon routes |
Manage routes |
routes |
gordon secrets |
Manage secrets |
secrets |
gordon status |
Show Gordon server status |
status |
gordon volumes |
Manage volumes |
- |
Client Commands
| Command |
Description |
Documentation |
gordon remotes |
Manage saved remote Gordon instances |
remotes |
gordon version |
Print version information |
serve |
gordon completion |
Generate shell autocompletion scripts |
- |
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
| Option |
Description |
-c, --config |
Path to configuration file |
--remote |
Remote Gordon URL (e.g., https://gordon.mydomain.com) |
--token |
Authentication token for remote |
--insecure |
Skip TLS certificate verification for remote HTTPS endpoints |
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
| Code |
Meaning |
| 0 |
Success |
| 1 |
General error |
| 2 |
Configuration error |
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)
source
1# CLI Commands
2
3Gordon provides a command-line interface for server management, deployment, and authentication.
4
5Most `list` commands also support `--json` for machine-readable output.
6
7Commands are organized by where they run:
8
9- **Server Commands** - Must run on the machine hosting Gordon
10- **Management Commands** - Work locally or remotely
11- **Client Commands** - CLI utilities that don't require a running Gordon server
12
13## Server Commands (local only)
14
15| Command | Description | Documentation |
16|---------|-------------|---------------|
17| `gordon serve` | Start the Gordon server | [serve](./serve.md) |
18| `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) |
19| `gordon ca` | Manage the internal Certificate Authority | [ca](./ca.md) |
20
21## Management Commands (local or remote)
22
23Management commands run locally through in-process services by default. Add `--remote` to target another Gordon instance.
24
25| Command | Description | Documentation |
26|---------|-------------|---------------|
27| `gordon attachments` | Manage container attachments | [attachments](./attachments.md) |
28| `gordon autoroute` | Manage auto-route domain allowlist | [autoroute](./autoroute.md) |
29| `gordon backups` | Manage database backups | [backup](./backup.md) |
30| `gordon bootstrap` | Configure a route, attachments, and secrets for an app | [bootstrap](./bootstrap.md) |
31| `gordon config show` | Show server configuration | [config](./config.md) |
32| `gordon deploy` | Manually deploy or redeploy a route | [serve](./serve.md#gordon-deploy) |
33| `gordon images` | List and prune images | [images](./images.md) |
34| `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
35| `gordon networks list` | List Gordon-managed Docker networks | [networks](./networks.md) |
36| `gordon preview` | Create or manage preview environments | [preview](../config/preview.md) |
37| `gordon push` | Tag, push, and optionally deploy an image | [push](./push.md) |
38| `gordon attachments push` | Build/push attachment images to registry | [attachments](./attachments.md) |
39| `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) |
40| `gordon restart` | Restart a running container | [restart](./restart.md) |
41| `gordon rollback` | Roll back to a previous image version | [rollback](./rollback.md) |
42| `gordon routes` | Manage routes | [routes](./routes.md) |
43| `gordon secrets` | Manage secrets | [secrets](./secrets.md) |
44| `gordon status` | Show Gordon server status | [status](./status.md) |
45| `gordon volumes` | Manage volumes | - |
46
47## Client Commands
48
49| Command | Description | Documentation |
50|---------|-------------|---------------|
51| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
52| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
53| `gordon completion` | Generate shell autocompletion scripts | - |
54
55## Quick Reference
56
57```bash
58# Start Gordon
59gordon serve
60gordon serve --config /path/to/config.toml
61
62# Reload configuration
63gordon reload
64
65# Deploy a specific route
66gordon deploy myapp.example.com
67
68# Restart a running container
69gordon restart myapp.example.com
70
71# First-time route setup
72gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
73
74# Then push and deploy
75gordon push app.example.com --build --no-confirm
76
77# Push an image and deploy
78gordon push myapp.example.com --build
79
80# Push and deploy without confirmation
81gordon push myapp.example.com --no-confirm
82
83# Roll back to a previous tag
84gordon rollback myapp.example.com
85
86# View logs
87gordon logs # Gordon process logs
88gordon logs -f # Follow process logs
89gordon logs -n 100 # Last 100 lines
90gordon logs myapp.local # Container logs for myapp.local
91gordon logs myapp.local -f # Follow container logs
92
93# Check version
94gordon version
95
96# Backups
97gordon backups list
98gordon backups run app.example.com
99gordon backups detect app.example.com
100gordon backups status
101
102# Images
103gordon images list
104gordon images prune --runtime-only
105gordon images prune --keep 3
106
107# Authentication
108gordon auth login --remote https://gordon.example.com --token $TOKEN
109gordon auth status
110gordon auth show-token
111gordon auth logout
112gordon auth token generate --subject ci-bot --expiry 0
113gordon auth token list
114gordon auth token revoke <token-id>
115gordon auth internal
116
117# Routes
118gordon routes list
119gordon routes add myapp.example.com myapp:latest
120gordon routes remove myapp.example.com
121gordon routes deploy myapp.example.com
122
123# Attachments
124gordon attachments list
125gordon attachments add app.example.com postgres:18
126gordon attachments remove app.example.com postgres:18
127
128# Secrets
129gordon secrets list myapp.local
130gordon secrets set myapp.local DATABASE_URL "postgres://..."
131gordon secrets remove myapp.local DATABASE_URL
132
133# Remotes
134gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
135gordon remotes list
136gordon remotes use prod
137
138# Preview environments
139gordon preview create app.example.com --branch feature-x
140gordon preview list
141gordon preview extend app.example.com --branch feature-x
142gordon preview delete app.example.com --branch feature-x
143
144# Volumes
145gordon volumes list
146gordon volumes prune
147
148# Auto-route allowlist
149gordon autoroute allow list
150gordon autoroute allow add example.com
151gordon autoroute allow add "*.staging.example.com"
152gordon autoroute allow remove example.com
153```
154
155## Global Options
156
157| Option | Description |
158|--------|-------------|
159| `-c, --config` | Path to configuration file |
160| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
161| `--token` | Authentication token for remote |
162| `--insecure` | Skip TLS certificate verification for remote HTTPS endpoints |
163
164### Remote Targeting
165
166The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
167or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
168when you want to bypass your saved configuration.
169
170**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.
171
172Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
173You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
174or in a specific entry in `~/.config/gordon/remotes.toml`.
175For Tailscale setups, you can also avoid `--insecure` by using the machine `*.ts.net` name with Tailscale-issued TLS certs in Gordon server config.
176Your public app domains can still use wildcard DNS and normal reverse-proxy routing.
177
178```bash
179# Using flags (use the gordon_domain from remote Gordon config)
180gordon routes list --remote https://gordon.example.com --token $TOKEN
181
182# Against self-signed/private CA endpoint
183gordon --remote https://gordon.example.com --token $TOKEN --insecure status
184
185# Using environment variables
186export GORDON_REMOTE=https://gordon.example.com
187export GORDON_TOKEN=$TOKEN
188export GORDON_INSECURE=true
189gordon routes list
190```
191
192## Exit Codes
193
194| Code | Meaning |
195|------|---------|
196| 0 | Success |
197| 1 | General error |
198| 2 | Configuration error |
199
200## Environment Variables
201
202Gordon reads configuration from environment variables:
203
204```bash
205GORDON_SERVER_PORT=8080 gordon serve
206GORDON_LOGGING_LEVEL=debug gordon serve
207```
208
209Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
210
211## Related
212
213- [Core Concepts](../concepts.md)
214- [Configuration Reference](../config/index.md)