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 remove

Remove a route.

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

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 remove
279
280Remove a route.
281
282```bash
283gordon routes remove <domain>
284gordon routes remove myapp.example.com
285```
286
287### Arguments
288
289| Argument | Description |
290|----------|-------------|
291| `<domain>` | The domain name of the route to remove |
292
293### Options
294
295| Option | Description |
296|--------|-------------|
297| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
298| `--token` | Authentication token for remote |
299
300### Examples
301
302```bash
303# Local
304gordon routes remove myapp.example.com
305
306# Remote (override)
307gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
308```
309
310---
311
312## gordon routes deploy
313
314Deploy or redeploy a specific route.
315
316```bash
317gordon routes deploy <domain>
318gordon routes deploy myapp.example.com
319```
320
321### Arguments
322
323| Argument | Description |
324|----------|-------------|
325| `<domain>` | The domain name of the route to deploy |
326
327### Options
328
329| Option | Description |
330|--------|-------------|
331| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
332| `--token` | Authentication token for remote |
333
334### Description
335
336Triggers a fresh image pull and container redeployment for the specified route.
337
338### Examples
339
340```bash
341# Local
342gordon routes deploy myapp.example.com
343
344# Remote (override)
345gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
346```
347
348## Related
349
350- [CLI Overview](./index.md)
351- [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 remove

Arguments

Options

Examples

gordon routes deploy

Arguments

Options

Description

Examples

Related

routes.md Raw History Folder