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 pin |
Pin a route to a specific image tag |
pin |
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 myapp:latest --domain app.example.com --build --no-confirm
# Push an image and deploy
gordon push myapp --build
# Push and deploy without confirmation
gordon push myapp --no-confirm
# Pin to a specific tag
gordon pin 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.example.com # Container logs for myapp.example.com
gordon logs myapp.example.com -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 status
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.example.com
gordon secrets set myapp.example.com DATABASE_URL "postgres://..."
gordon secrets remove myapp.example.com 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, -r |
Remote name or URL (e.g., prod, 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.
gordon routes list and gordon routes status are the exceptions: when neither --remote
nor GORDON_REMOTE is set, they show local routes first, then every saved remote. Set either
one to force a single target.
# Aggregate routes views
gordon routes list
gordon routes status
# Single-target override
gordon routes list --remote prod
GORDON_REMOTE=prod gordon routes status
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.
If remote CLI gets a 404 during /auth/token exchange, the server likely still sets only server.registry_domain and needs server.gordon_domain configured.
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 pin` | Pin a route to a specific image tag | [pin](./pin.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 myapp:latest --domain app.example.com --build --no-confirm
76
77# Push an image and deploy
78gordon push myapp --build
79
80# Push and deploy without confirmation
81gordon push myapp --no-confirm
82
83# Pin to a specific tag
84gordon pin 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.example.com # Container logs for myapp.example.com
91gordon logs myapp.example.com -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 status
120gordon routes add myapp.example.com myapp:latest
121gordon routes remove myapp.example.com
122gordon routes deploy myapp.example.com
123
124# Attachments
125gordon attachments list
126gordon attachments add app.example.com postgres:18
127gordon attachments remove app.example.com postgres:18
128
129# Secrets
130gordon secrets list myapp.example.com
131gordon secrets set myapp.example.com DATABASE_URL "postgres://..."
132gordon secrets remove myapp.example.com DATABASE_URL
133
134# Remotes
135gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
136gordon remotes list
137gordon remotes use prod
138
139# Preview environments
140gordon preview create app.example.com --branch feature-x
141gordon preview list
142gordon preview extend app.example.com --branch feature-x
143gordon preview delete app.example.com --branch feature-x
144
145# Volumes
146gordon volumes list
147gordon volumes prune
148
149# Auto-route allowlist
150gordon autoroute allow list
151gordon autoroute allow add example.com
152gordon autoroute allow add "*.staging.example.com"
153gordon autoroute allow remove example.com
154```
155
156## Global Options
157
158| Option | Description |
159|--------|-------------|
160| `-c, --config` | Path to configuration file |
161| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
162| `--token` | Authentication token for remote |
163| `--insecure` | Skip TLS certificate verification for remote HTTPS endpoints |
164
165### Remote Targeting
166
167The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
168or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
169when you want to bypass your saved configuration.
170
171`gordon routes list` and `gordon routes status` are the exceptions: when neither `--remote`
172nor `GORDON_REMOTE` is set, they show local routes first, then every saved remote. Set either
173one to force a single target.
174
175```bash
176# Aggregate routes views
177gordon routes list
178gordon routes status
179
180# Single-target override
181gordon routes list --remote prod
182GORDON_REMOTE=prod gordon routes status
183```
184
185**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.
186If remote CLI gets a `404` during `/auth/token` exchange, the server likely still sets only `server.registry_domain` and needs `server.gordon_domain` configured.
187
188Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
189You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
190or in a specific entry in `~/.config/gordon/remotes.toml`.
191For Tailscale setups, you can also avoid `--insecure` by using the machine `*.ts.net` name with Tailscale-issued TLS certs in Gordon server config.
192Your public app domains can still use wildcard DNS and normal reverse-proxy routing.
193
194```bash
195# Using flags (use the gordon_domain from remote Gordon config)
196gordon routes list --remote https://gordon.example.com --token $TOKEN
197
198# Against self-signed/private CA endpoint
199gordon --remote https://gordon.example.com --token $TOKEN --insecure status
200
201# Using environment variables
202export GORDON_REMOTE=https://gordon.example.com
203export GORDON_TOKEN=$TOKEN
204export GORDON_INSECURE=true
205gordon routes list
206```
207
208## Exit Codes
209
210| Code | Meaning |
211|------|---------|
212| 0 | Success |
213| 1 | General error |
214| 2 | Configuration error |
215
216## Environment Variables
217
218Gordon reads configuration from environment variables:
219
220```bash
221GORDON_SERVER_PORT=8080 gordon serve
222GORDON_LOGGING_LEVEL=debug gordon serve
223```
224
225Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
226
227## Related
228
229- [Core Concepts](../concepts.md)
230- [Configuration Reference](../config/index.md)