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