1# Routes Commands
2
3Manage routes on local or remote Gordon instances.
4
5Remote targeting uses client config or an active remote by default.
6Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
7
8## gordon routes
9
10### Subcommands
11
12| Subcommand | Description |
13|------------|-------------|
14| `list` | List all routes |
15| `show` | Show details for a single route |
16| `add` | Create or update a route |
17| `remove` | Remove a route |
18| `deploy` | Deploy a specific route |
19
20---
21
22## gordon routes list
23
24List all configured routes.
25
26```bash
27gordon routes list
28gordon routes list --json
29gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
30```
31
32### Output
33
34```
35Domain                    Image                     Status
36--------------------------------------------------------------------------------
37app.example.com           myapp:latest              running
38api.example.com           myapi:v2.1.0              running
39admin.example.com         admin-panel:latest        stopped
40```
41
42### JSON Output
43
44```bash
45gordon routes list --json
46```
47
48```json
49[
50  {
51    "domain": "app.example.com",
52    "image": "myapp:latest",
53    "status": "running"
54  },
55  {
56    "domain": "api.example.com",
57    "image": "myapi:v2.1.0",
58    "status": "running"
59  }
60]
61```
62
63### Options
64
65| Option | Description |
66|--------|-------------|
67| `--json` | Output routes as JSON |
68| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
69| `--token` | Authentication token for remote |
70
71---
72
73## gordon routes add
74
75Create a new route or update an existing route.
76
77```bash
78gordon routes add <domain> <image>
79gordon routes add myapp.example.com myapp:latest
80```
81
82If the route already exists, Gordon updates it to the new image instead of failing.
83The image does not need to be pushed to the Gordon registry before you add the route.
84
85### Arguments
86
87| Argument | Description |
88|----------|-------------|
89| `<domain>` | The domain name for the route |
90| `<image>` | The container image to deploy |
91
92### Options
93
94| Option | Description |
95|--------|-------------|
96| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
97| `--token` | Authentication token for remote |
98
99### Examples
100
101```bash
102# Local
103gordon routes add myapp.example.com myapp:latest
104gordon routes add api.example.com myapi:v2.1.0
105
106# Update an existing route
107gordon routes add myapp.example.com myapp:v2
108
109# Remote (override)
110gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
111```
112
113### Notes
114
115- `gordon routes add` is idempotent: it creates the route when missing and updates it when present.
116- 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.
117
118---
119
120## gordon routes show
121
122Show detailed information about a single route.
123
124```bash
125gordon routes show <domain>
126gordon routes show myapp.example.com
127gordon routes show myapp.example.com --json
128```
129
130### Arguments
131
132| Argument | Description |
133|----------|-------------|
134| `<domain>` | The domain name of the route to inspect |
135
136### Options
137
138| Option | Description |
139|--------|-------------|
140| `--json` | Output route details as JSON |
141| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
142| `--token` | Authentication token for remote |
143
144### Description
145
146Displays the configured image for the route plus any available container and HTTP health information.
147In local-only mode, health data may be unavailable.
148
149### Examples
150
151```bash
152# Local
153gordon routes show myapp.example.com
154
155# JSON
156gordon routes show myapp.example.com --json
157
158# Remote (override)
159gordon routes show myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
160```
161
162### JSON Output
163
164```json
165{
166  "domain": "myapp.example.com",
167  "image": "myapp:latest",
168  "container_status": "running",
169  "http_status": 200
170}
171```
172
173---
174
175## gordon routes remove
176
177Remove a route.
178
179```bash
180gordon routes remove <domain>
181gordon routes remove myapp.example.com
182```
183
184### Arguments
185
186| Argument | Description |
187|----------|-------------|
188| `<domain>` | The domain name of the route to remove |
189
190### Options
191
192| Option | Description |
193|--------|-------------|
194| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
195| `--token` | Authentication token for remote |
196
197### Examples
198
199```bash
200# Local
201gordon routes remove myapp.example.com
202
203# Remote (override)
204gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
205```
206
207---
208
209## gordon routes deploy
210
211Deploy or redeploy a specific route.
212
213```bash
214gordon routes deploy <domain>
215gordon routes deploy myapp.example.com
216```
217
218### Arguments
219
220| Argument | Description |
221|----------|-------------|
222| `<domain>` | The domain name of the route to deploy |
223
224### Options
225
226| Option | Description |
227|--------|-------------|
228| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
229| `--token` | Authentication token for remote |
230
231### Description
232
233Triggers a fresh image pull and container redeployment for the specified route.
234
235### Examples
236
237```bash
238# Local
239gordon routes deploy myapp.example.com
240
241# Remote (override)
242gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
243```
244
245## Related
246
247- [CLI Overview](./index.md)
248- [Routes Configuration](../config/routes.md)