index.md Raw History Folder

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 traffic`	Inspect traffic plane status	traffic
`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

# Traffic plane
gordon traffic status --remote prod
gordon traffic status --remote prod --json

# 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.

When no explicit remote is selected and no active remote is configured, Gordon can now auto-infer a saved remote for commands that already have a concrete target. It probes your saved remotes and uses the remote automatically when exactly one matches. If multiple remotes match, Gordon stops with an ambiguity error and asks you to use --remote. If any remote probe fails, Gordon also stops rather than guessing.

Auto-inference currently applies to target-based commands such as:

gordon push
gordon attachments push
gordon deploy <domain>
gordon restart <domain>
gordon pin <domain> / gordon pin list <domain>
gordon routes show <domain> / gordon routes remove <domain>
gordon secrets list|set|remove <domain>
gordon attachments list <target> / gordon attachments add|remove <target> ...
gordon backups list <domain> / gordon backups run <domain> / gordon backups detect <domain>
gordon images tags <repository>
gordon logs <domain>

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

# Auto-inferred single match from saved remotes
gordon push myapp --build
gordon deploy app.example.com

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_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 traffic` | Inspect traffic plane status | [traffic](./traffic.md) |
46| `gordon volumes` | Manage volumes | - |
47
48## Client Commands
49
50| Command | Description | Documentation |
51|---------|-------------|---------------|
52| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
53| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
54| `gordon completion` | Generate shell autocompletion scripts | - |
55
56## Quick Reference
57
58```bash
59# Start Gordon
60gordon serve
61gordon serve --config /path/to/config.toml
62
63# Reload configuration
64gordon reload
65
66# Deploy a specific route
67gordon deploy myapp.example.com
68
69# Restart a running container
70gordon restart myapp.example.com
71
72# First-time route setup
73gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
74
75# Then push and deploy
76gordon push myapp:latest --domain app.example.com --build --no-confirm
77
78# Push an image and deploy
79gordon push myapp --build
80
81# Push and deploy without confirmation
82gordon push myapp --no-confirm
83
84# Pin to a specific tag
85gordon pin myapp.example.com
86
87# View logs
88gordon logs                          # Gordon process logs
89gordon logs -f                       # Follow process logs
90gordon logs -n 100                   # Last 100 lines
91gordon logs myapp.example.com       # Container logs for myapp.example.com
92gordon logs myapp.example.com -f    # Follow container logs
93
94# Check version
95gordon version
96
97# Traffic plane
98gordon traffic status --remote prod
99gordon traffic status --remote prod --json
100
101# Backups
102gordon backups list
103gordon backups run app.example.com
104gordon backups detect app.example.com
105gordon backups status
106
107# Images
108gordon images list
109gordon images prune --runtime-only
110gordon images prune --keep 3
111
112# Authentication
113gordon auth login --remote https://gordon.example.com --token $TOKEN
114gordon auth status
115gordon auth show-token
116gordon auth logout
117gordon auth token generate --subject ci-bot --expiry 0
118gordon auth token list
119gordon auth token revoke <token-id>
120gordon auth internal
121
122# Routes
123gordon routes list
124gordon routes status
125gordon routes add myapp.example.com myapp:latest
126gordon routes remove myapp.example.com
127gordon routes deploy myapp.example.com
128
129# Attachments
130gordon attachments list
131gordon attachments add app.example.com postgres:18
132gordon attachments remove app.example.com postgres:18
133
134# Secrets
135gordon secrets list myapp.example.com
136gordon secrets set myapp.example.com DATABASE_URL "postgres://..."
137gordon secrets remove myapp.example.com DATABASE_URL
138
139# Remotes
140gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
141gordon remotes list
142gordon remotes use prod
143
144# Preview environments
145gordon preview create app.example.com --branch feature-x
146gordon preview list
147gordon preview extend app.example.com --branch feature-x
148gordon preview delete app.example.com --branch feature-x
149
150# Volumes
151gordon volumes list
152gordon volumes prune
153
154# Auto-route allowlist
155gordon autoroute allow list
156gordon autoroute allow add example.com
157gordon autoroute allow add "*.staging.example.com"
158gordon autoroute allow remove example.com
159```
160
161## Global Options
162
163| Option | Description |
164|--------|-------------|
165| `-c, --config` | Path to configuration file |
166| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
167| `--token` | Authentication token for remote |
168| `--insecure` | Skip TLS certificate verification for remote HTTPS endpoints |
169
170### Remote Targeting
171
172The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
173or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
174when you want to bypass your saved configuration.
175
176When no explicit remote is selected and no active remote is configured, Gordon can now
177**auto-infer a saved remote** for commands that already have a concrete target. It probes your
178saved remotes and uses the remote automatically when exactly one matches. If multiple remotes
179match, Gordon stops with an ambiguity error and asks you to use `--remote`. If any remote probe
180fails, Gordon also stops rather than guessing.
181
182Auto-inference currently applies to target-based commands such as:
183- `gordon push`
184- `gordon attachments push`
185- `gordon deploy <domain>`
186- `gordon restart <domain>`
187- `gordon pin <domain>` / `gordon pin list <domain>`
188- `gordon routes show <domain>` / `gordon routes remove <domain>`
189- `gordon secrets list|set|remove <domain>`
190- `gordon attachments list <target>` / `gordon attachments add|remove <target> ...`
191- `gordon backups list <domain>` / `gordon backups run <domain>` / `gordon backups detect <domain>`
192- `gordon images tags <repository>`
193- `gordon logs <domain>`
194
195`gordon routes list` and `gordon routes status` are the exceptions: when neither `--remote`
196nor `GORDON_REMOTE` is set, they show local routes first, then every saved remote. Set either
197one to force a single target.
198
199```bash
200# Aggregate routes views
201gordon routes list
202gordon routes status
203
204# Single-target override
205gordon routes list --remote prod
206GORDON_REMOTE=prod gordon routes status
207
208# Auto-inferred single match from saved remotes
209gordon push myapp --build
210gordon deploy app.example.com
211```
212
213**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.
214If remote CLI gets a `404` during `/auth/token` exchange, the server likely still sets only `server.registry_domain` and needs `server.gordon_domain` configured.
215
216Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
217You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
218or in a specific entry in `~/.config/gordon/remotes.toml`.
219For Tailscale setups, you can also avoid `--insecure` by using the machine `*.ts.net` name with Tailscale-issued TLS certs in Gordon server config.
220Your public app domains can still use wildcard DNS and normal reverse-proxy routing.
221
222```bash
223# Using flags (use the gordon_domain from remote Gordon config)
224gordon routes list --remote https://gordon.example.com --token $TOKEN
225
226# Against self-signed/private CA endpoint
227gordon --remote https://gordon.example.com --token $TOKEN --insecure status
228
229# Using environment variables
230export GORDON_REMOTE=https://gordon.example.com
231export GORDON_TOKEN=$TOKEN
232export GORDON_INSECURE=true
233gordon routes list
234```
235
236## Exit Codes
237
238| Code | Meaning |
239|------|---------|
240| 0 | Success |
241| 1 | General error |
242| 2 | Configuration error |
243
244## Environment Variables
245
246Gordon reads configuration from environment variables:
247
248```bash
249GORDON_LOGGING_LEVEL=debug gordon serve
250```
251
252Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
253
254## Related
255
256- [Core Concepts](../concepts.md)
257- [Configuration Reference](../config/index.md)

index.md RawHistoryFolder