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