routes.md Raw History Folder

Routes Commands

Manage routes on local or remote Gordon instances.

Most remote-capable commands use client config or an active remote by default. gordon routes list and gordon routes status are different: when neither --remote nor GORDON_REMOTE is set, they show local routes first, then each saved remote under its own heading. See CLI Overview.

gordon routes

Subcommands

Subcommand	Description
`list`	List routes by domain and image
`status`	Show detailed route status
`show`	Show details for a single route
`add`	Create or update a route
`remove`	Remove a route
`deploy`	Deploy a specific route

gordon routes list

List routes by domain and image only.

When no target is selected, Gordon shows local routes first, then each saved remote under its own heading. Use --remote or GORDON_REMOTE to show one target only.

gordon routes list
gordon routes list --json
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
GORDON_REMOTE=prod gordon routes list

Output

Routes

Local
  app.example.com           myapp:latest
  api.example.com           myapi:v2.1.0

Remote: hetzner-vps
  gordon.example.com        gordon-webapp:latest

Remote: igor
  grafana.supri.xyz         grafana
  test.supri.xyz            hello-test

JSON Output

gordon routes list --json

[
  {
    "kind": "local",
    "name": "local",
    "routes": [
      {
        "domain": "app.example.com",
        "image": "myapp:latest"
      }
    ]
  },
  {
    "kind": "remote",
    "name": "igor",
    "url": "https://gordon.supri.xyz",
    "routes": [
      {
        "domain": "grafana.supri.xyz",
        "image": "grafana"
      }
    ]
  }
]

Single-target mode still returns a one-element array. Sections can also include an error field when a target is unavailable.

Options

Option	Description
`--json`	Output routes as JSON
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

gordon routes status

Show detailed route status for each target.

routes status uses the same target selection rules as routes list. When no target is selected, Gordon shows local status first, then each saved remote under its own heading.

gordon routes status
gordon routes status --json
gordon routes status --remote https://gordon.mydomain.com --token $TOKEN
GORDON_REMOTE=prod gordon routes status

Output

Route Status

Local
  <rich tree for local routes>

Remote: hetzner-vps
  <rich tree for that remote>

Remote: igor
  <rich tree for that remote>

The rich view keeps network grouping, container status, HTTP probe status, and attachments within each target.

JSON Output

[
  {
    "kind": "local",
    "name": "local",
    "routes": [
      {
        "domain": "app.example.com",
        "image": "myapp:latest",
        "container_id": "abcd1234",
        "container_status": "running",
        "http_status": 200,
        "network": "gordon-shared",
        "attachments": [
          {
            "name": "postgres",
            "image": "postgres:18",
            "status": "running"
          }
        ]
      }
    ]
  }
]

Single-target mode still returns a one-element array. Sections can also include an error field when a target is unavailable.

Options

Option	Description
`--json`	Output routes as JSON
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

gordon routes add

Create a new route or update an existing route.

gordon routes add <domain> <image>
gordon routes add myapp.example.com myapp:latest

If the route already exists, Gordon updates it to the new image instead of failing. The image does not need to be pushed to the Gordon registry before you add the route.

Arguments

Argument	Description
`<domain>`	The domain name for the route
`<image>`	The container image to deploy

Options

Option	Description
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Examples

# Local
gordon routes add myapp.example.com myapp:latest
gordon routes add api.example.com myapi:v2.1.0

# Update an existing route
gordon routes add myapp.example.com myapp:v2

# Remote (override)
gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN

Notes

gordon routes add is idempotent: it creates the route when missing and updates it when present.
You can add the route before the image is pushed. Deploy happens when the image is later available or when you deploy an available image.

gordon routes show

Show detailed information about a single route.

gordon routes show <domain>
gordon routes show myapp.example.com
gordon routes show myapp.example.com --json

Arguments

Argument	Description
`<domain>`	The domain name of the route to inspect

Options

Option	Description
`--json`	Output route details as JSON
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Description

Displays the configured image for the route plus any available container and HTTP health information. In local-only mode, health data may be unavailable.

Examples

# Local
gordon routes show myapp.example.com

# JSON
gordon routes show myapp.example.com --json

# Remote (override)
gordon routes show myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN

JSON Output

{
  "domain": "myapp.example.com",
  "image": "myapp:latest",
  "container_status": "running",
  "http_status": 200
}

gordon routes diagnose

Diagnose route configuration, runtime state, preserved volumes, and orphaned attachment containers.

gordon routes diagnose <domain>
gordon routes diagnose myapp.example.com --json

Use this after route deletion or failed deployment to see whether runtime state still exists and which safe cleanup commands to run next.

Output

Route diagnosis: myapp.example.com
Image: myapp:latest
Container: running abc123def456
Preserved volume: gordon-myapp-example-com-data
Orphaned attachment: postgres
Hint: persistent volumes are preserved by default
Hint: run 'gordon attachments prune --stop' to stop orphaned attachment containers while preserving volumes

JSON Output

{
  "domain": "myapp.example.com",
  "configured": true,
  "route": {"domain": "myapp.example.com", "image": "myapp:latest", "https": true},
  "runtime": {"domain": "myapp.example.com", "container_id": "abc123def456", "container_status": "running"},
  "volumes": [{"name": "gordon-myapp-example-com-data", "in_use": false}],
  "orphaned_attachments": [{"container_id": "pg123", "name": "postgres", "image": "postgres:16", "status": "running", "owner": "myapp.example.com"}],
  "hints": ["persistent volumes are preserved by default"]
}

Next Steps

gordon routes purge myapp.example.com          # dry-run retained resources
gordon routes purge myapp.example.com --attachments --force

gordon routes purge

Review retained resources for a route and execute supported explicit cleanup actions only when forced.

gordon routes purge myapp.example.com              # dry-run
gordon routes purge myapp.example.com --attachments --force
gordon routes purge myapp.example.com --volumes    # report preserved volumes for manual review

Dry-run Output

Purge dry-run: myapp.example.com
Preserved attachments:
  postgres (running)
Purge candidate: route_container abc123def456
Preserved volume: gordon-myapp-example-com-data
Hint: dry-run only; add --force with explicit category flags to execute supported purge actions

Forced Attachment Cleanup Output

Purge completed: myapp.example.com
Removed containers:
  postgres
Hint: attachment volumes and data were preserved

Purge is intentionally conservative. Volumes are reported and preserved unless a dedicated volume deletion flow supports safe targeted deletion.

gordon routes remove

Remove a route.

Route removal is safe by default. Gordon removes the route from configuration and reconciles the active route container so it is no longer served or restarted by Gordon's monitor. Stateful data is preserved. Volumes and attachment data are not deleted unless a separate explicit purge flow requests destructive cleanup.

gordon routes remove <domain>
gordon routes remove myapp.example.com

Arguments

Argument	Description
`<domain>`	The domain name of the route to remove

Options

Option	Description
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Examples

# Local
gordon routes remove myapp.example.com

# Remote (override)
gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN

# Typical output
Route removed: myapp.example.com

Removed containers:
  gordon-myapp.example.com (abc123def456)

Preserved attachments:
  postgres (running)

gordon routes deploy

Deploy or redeploy a specific route.

gordon routes deploy <domain>
gordon routes deploy myapp.example.com

Arguments

Argument	Description
`<domain>`	The domain name of the route to deploy

Options

Option	Description
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Description

Triggers a fresh image pull and container redeployment for the specified route.

Examples

# Local
gordon routes deploy myapp.example.com

# Remote (override)
gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN

source

1# Routes Commands
2
3Manage routes on local or remote Gordon instances.
4
5Most remote-capable commands use client config or an active remote by default.
6`gordon routes list` and `gordon routes status` are different: when neither
7`--remote` nor `GORDON_REMOTE` is set, they show local routes first, then each
8saved remote under its own heading. See [CLI Overview](./index.md).
9
10## gordon routes
11
12### Subcommands
13
14| Subcommand | Description |
15|------------|-------------|
16| `list` | List routes by domain and image |
17| `status` | Show detailed route status |
18| `show` | Show details for a single route |
19| `add` | Create or update a route |
20| `remove` | Remove a route |
21| `deploy` | Deploy a specific route |
22
23---
24
25## gordon routes list
26
27List routes by domain and image only.
28
29When no target is selected, Gordon shows local routes first, then each saved
30remote under its own heading. Use `--remote` or `GORDON_REMOTE` to show one
31target only.
32
33```bash
34gordon routes list
35gordon routes list --json
36gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
37GORDON_REMOTE=prod gordon routes list
38```
39
40### Output
41
42```text
43Routes
44
45Local
46  app.example.com           myapp:latest
47  api.example.com           myapi:v2.1.0
48
49Remote: hetzner-vps
50  gordon.example.com        gordon-webapp:latest
51
52Remote: igor
53  grafana.supri.xyz         grafana
54  test.supri.xyz            hello-test
55```
56
57### JSON Output
58
59```bash
60gordon routes list --json
61```
62
63```json
64[
65  {
66    "kind": "local",
67    "name": "local",
68    "routes": [
69      {
70        "domain": "app.example.com",
71        "image": "myapp:latest"
72      }
73    ]
74  },
75  {
76    "kind": "remote",
77    "name": "igor",
78    "url": "https://gordon.supri.xyz",
79    "routes": [
80      {
81        "domain": "grafana.supri.xyz",
82        "image": "grafana"
83      }
84    ]
85  }
86]
87```
88
89Single-target mode still returns a one-element array. Sections can also include
90an `error` field when a target is unavailable.
91
92### Options
93
94| Option | Description |
95|--------|-------------|
96| `--json` | Output routes as JSON |
97| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
98| `--token` | Authentication token for remote |
99
100---
101
102## gordon routes status
103
104Show detailed route status for each target.
105
106`routes status` uses the same target selection rules as `routes list`. When no
107target is selected, Gordon shows local status first, then each saved remote
108under its own heading.
109
110```bash
111gordon routes status
112gordon routes status --json
113gordon routes status --remote https://gordon.mydomain.com --token $TOKEN
114GORDON_REMOTE=prod gordon routes status
115```
116
117### Output
118
119```text
120Route Status
121
122Local
123  <rich tree for local routes>
124
125Remote: hetzner-vps
126  <rich tree for that remote>
127
128Remote: igor
129  <rich tree for that remote>
130```
131
132The rich view keeps network grouping, container status, HTTP probe status, and
133attachments within each target.
134
135### JSON Output
136
137```json
138[
139  {
140    "kind": "local",
141    "name": "local",
142    "routes": [
143      {
144        "domain": "app.example.com",
145        "image": "myapp:latest",
146        "container_id": "abcd1234",
147        "container_status": "running",
148        "http_status": 200,
149        "network": "gordon-shared",
150        "attachments": [
151          {
152            "name": "postgres",
153            "image": "postgres:18",
154            "status": "running"
155          }
156        ]
157      }
158    ]
159  }
160]
161```
162
163Single-target mode still returns a one-element array. Sections can also include
164an `error` field when a target is unavailable.
165
166### Options
167
168| Option | Description |
169|--------|-------------|
170| `--json` | Output routes as JSON |
171| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
172| `--token` | Authentication token for remote |
173
174---
175
176## gordon routes add
177
178Create a new route or update an existing route.
179
180```bash
181gordon routes add <domain> <image>
182gordon routes add myapp.example.com myapp:latest
183```
184
185If the route already exists, Gordon updates it to the new image instead of failing.
186The image does not need to be pushed to the Gordon registry before you add the route.
187
188### Arguments
189
190| Argument | Description |
191|----------|-------------|
192| `<domain>` | The domain name for the route |
193| `<image>` | The container image to deploy |
194
195### Options
196
197| Option | Description |
198|--------|-------------|
199| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
200| `--token` | Authentication token for remote |
201
202### Examples
203
204```bash
205# Local
206gordon routes add myapp.example.com myapp:latest
207gordon routes add api.example.com myapi:v2.1.0
208
209# Update an existing route
210gordon routes add myapp.example.com myapp:v2
211
212# Remote (override)
213gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
214```
215
216### Notes
217
218- `gordon routes add` is idempotent: it creates the route when missing and updates it when present.
219- You can add the route before the image is pushed. Deploy happens when the image is later available or when you deploy an available image.
220
221---
222
223## gordon routes show
224
225Show detailed information about a single route.
226
227```bash
228gordon routes show <domain>
229gordon routes show myapp.example.com
230gordon routes show myapp.example.com --json
231```
232
233### Arguments
234
235| Argument | Description |
236|----------|-------------|
237| `<domain>` | The domain name of the route to inspect |
238
239### Options
240
241| Option | Description |
242|--------|-------------|
243| `--json` | Output route details as JSON |
244| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
245| `--token` | Authentication token for remote |
246
247### Description
248
249Displays the configured image for the route plus any available container and HTTP health information.
250In local-only mode, health data may be unavailable.
251
252### Examples
253
254```bash
255# Local
256gordon routes show myapp.example.com
257
258# JSON
259gordon routes show myapp.example.com --json
260
261# Remote (override)
262gordon routes show myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
263```
264
265### JSON Output
266
267```json
268{
269  "domain": "myapp.example.com",
270  "image": "myapp:latest",
271  "container_status": "running",
272  "http_status": 200
273}
274```
275
276---
277
278## gordon routes diagnose
279
280Diagnose route configuration, runtime state, preserved volumes, and orphaned attachment containers.
281
282```bash
283gordon routes diagnose <domain>
284gordon routes diagnose myapp.example.com --json
285```
286
287Use this after route deletion or failed deployment to see whether runtime state still exists and which safe cleanup commands to run next.
288
289### Output
290
291```text
292Route diagnosis: myapp.example.com
293Image: myapp:latest
294Container: running abc123def456
295Preserved volume: gordon-myapp-example-com-data
296Orphaned attachment: postgres
297Hint: persistent volumes are preserved by default
298Hint: run 'gordon attachments prune --stop' to stop orphaned attachment containers while preserving volumes
299```
300
301### JSON Output
302
303```json
304{
305  "domain": "myapp.example.com",
306  "configured": true,
307  "route": {"domain": "myapp.example.com", "image": "myapp:latest", "https": true},
308  "runtime": {"domain": "myapp.example.com", "container_id": "abc123def456", "container_status": "running"},
309  "volumes": [{"name": "gordon-myapp-example-com-data", "in_use": false}],
310  "orphaned_attachments": [{"container_id": "pg123", "name": "postgres", "image": "postgres:16", "status": "running", "owner": "myapp.example.com"}],
311  "hints": ["persistent volumes are preserved by default"]
312}
313```
314
315### Next Steps
316
317```bash
318gordon routes purge myapp.example.com          # dry-run retained resources
319gordon routes purge myapp.example.com --attachments --force
320```
321
322---
323
324## gordon routes purge
325
326Review retained resources for a route and execute supported explicit cleanup actions only when forced.
327
328```bash
329gordon routes purge myapp.example.com              # dry-run
330gordon routes purge myapp.example.com --attachments --force
331gordon routes purge myapp.example.com --volumes    # report preserved volumes for manual review
332```
333
334### Dry-run Output
335
336```text
337Purge dry-run: myapp.example.com
338Preserved attachments:
339  postgres (running)
340Purge candidate: route_container abc123def456
341Preserved volume: gordon-myapp-example-com-data
342Hint: dry-run only; add --force with explicit category flags to execute supported purge actions
343```
344
345### Forced Attachment Cleanup Output
346
347```text
348Purge completed: myapp.example.com
349Removed containers:
350  postgres
351Hint: attachment volumes and data were preserved
352```
353
354Purge is intentionally conservative. Volumes are reported and preserved unless a dedicated volume deletion flow supports safe targeted deletion.
355
356---
357
358## gordon routes remove
359
360Remove a route.
361
362Route removal is safe by default. Gordon removes the route from configuration and reconciles the active route container so it is no longer served or restarted by Gordon's monitor. Stateful data is preserved. Volumes and attachment data are not deleted unless a separate explicit purge flow requests destructive cleanup.
363
364```bash
365gordon routes remove <domain>
366gordon routes remove myapp.example.com
367```
368
369### Arguments
370
371| Argument | Description |
372|----------|-------------|
373| `<domain>` | The domain name of the route to remove |
374
375### Options
376
377| Option | Description |
378|--------|-------------|
379| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
380| `--token` | Authentication token for remote |
381
382### Examples
383
384```bash
385# Local
386gordon routes remove myapp.example.com
387
388# Remote (override)
389gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
390
391# Typical output
392Route removed: myapp.example.com
393
394Removed containers:
395  gordon-myapp.example.com (abc123def456)
396
397Preserved attachments:
398  postgres (running)
399```
400
401---
402
403## gordon routes deploy
404
405Deploy or redeploy a specific route.
406
407```bash
408gordon routes deploy <domain>
409gordon routes deploy myapp.example.com
410```
411
412### Arguments
413
414| Argument | Description |
415|----------|-------------|
416| `<domain>` | The domain name of the route to deploy |
417
418### Options
419
420| Option | Description |
421|--------|-------------|
422| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
423| `--token` | Authentication token for remote |
424
425### Description
426
427Triggers a fresh image pull and container redeployment for the specified route.
428
429### Examples
430
431```bash
432# Local
433gordon routes deploy myapp.example.com
434
435# Remote (override)
436gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
437```
438
439## Related
440
441- [CLI Overview](./index.md)
442- [Routes Configuration](../config/routes.md)

routes.md RawHistoryFolder

Routes Commands

gordon routes

Subcommands

gordon routes list

Output

JSON Output

Options

gordon routes status

Output

JSON Output

Options

gordon routes add

Arguments

Options

Examples

Notes

gordon routes show

Arguments

Options

Description

Examples

JSON Output

gordon routes diagnose

Output

JSON Output

Next Steps

gordon routes purge

Dry-run Output

Forced Attachment Cleanup Output

gordon routes remove

Arguments

Options

Examples

gordon routes deploy

Arguments

Options

Description

Examples

Related

routes.md Raw History Folder