1# Auto-Route Commands
2
3Manage the auto-route domain allowlist on local or remote Gordon instances.
4
5When auto-route is enabled, Gordon handles image pushes in two ways:
6
71. **Image-name matching** — when a pushed image matches an existing route's configured image, Gordon auto-deploys that route. Since the route already exists, no allowlist check is needed.
82. **Label-based creation** — when a pushed image carries `gordon.domain` labels, Gordon creates new routes for those domains. The domain allowlist restricts which domains may be created this way, preventing untrusted images from registering arbitrary domains.
9
10The allowlist gates only the creation of new routes from labels. Routes created manually with `gordon routes add` or already present in configuration are not subject to the allowlist.
11
12Remote targeting uses client config or an active remote by default.
13Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
14
15## gordon autoroute
16
17Manage auto-route settings.
18
19### Subcommands
20
21| Subcommand | Description |
22|------------|-------------|
23| `allow` | Manage auto-route allowed domains |
24
25---
26
27## gordon autoroute allow
28
29Manage auto-route allowed domains.
30
31### Subcommands
32
33| Subcommand | Description |
34|------------|-------------|
35| `add` | Add a domain pattern to the allowlist |
36| `list` | List allowed domains |
37| `remove` | Remove a domain pattern |
38
39---
40
41## gordon autoroute allow add
42
43Add a domain pattern to the auto-route allowlist.
44
45```bash
46gordon autoroute allow add <pattern>
47gordon autoroute allow add example.com
48gordon autoroute allow add "*.staging.example.com"
49gordon autoroute allow add example.com --remote https://gordon.mydomain.com --token $TOKEN
50```
51
52### Arguments
53
54| Argument | Description |
55|----------|-------------|
56| `<pattern>` | Domain pattern to allow for auto-route |
57
58### Options
59
60| Option | Description |
61|--------|-------------|
62| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
63| `--token` | Authentication token for remote |
64
65### Description
66
67Patterns must be lowercase and must not have trailing dots.
68A bare `*` matches all domains. Wildcards in `*.domain.tld` form match exactly one subdomain level, so `*.example.com` matches `app.example.com` but not `api.app.example.com`.
69
70### Examples
71
72```bash
73# Allow an exact domain
74gordon autoroute allow add example.com
75
76# Allow one subdomain level under staging.example.com
77gordon autoroute allow add "*.staging.example.com"
78
79# Remote (override)
80gordon autoroute allow add example.com --remote https://gordon.mydomain.com --token $TOKEN
81```
82
83### Output
84
85```text
86✓ Allowed domain added
87```
88
89---
90
91## gordon autoroute allow list
92
93List auto-route allowed domains.
94
95```bash
96gordon autoroute allow list
97gordon autoroute allow list --json
98gordon autoroute allow list --remote https://gordon.mydomain.com --token $TOKEN
99```
100
101### Options
102
103| Option | Description |
104|--------|-------------|
105| `--json` | Output allowed domains as JSON |
106| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
107| `--token` | Authentication token for remote |
108
109### Description
110
111Shows the current allowlist used to restrict which domains auto-route may claim.
112When no patterns are configured, the command prints a friendly empty-state message instead of a table.
113
114### Examples
115
116```bash
117# Local
118gordon autoroute allow list
119
120# JSON
121gordon autoroute allow list --json
122
123# Remote (override)
124gordon autoroute allow list --remote https://gordon.mydomain.com --token $TOKEN
125```
126
127### Output
128
129```text
130example.com
131*.staging.example.com
132```
133
134When the allowlist is empty:
135
136```text
137No allowed domains configured
138```
139
140### JSON Output
141
142```bash
143gordon autoroute allow list --json
144```
145
146```json
147{
148  "domains": ["example.com", "*.staging.example.com"]
149}
150```
151
152---
153
154## gordon autoroute allow remove
155
156Remove a domain pattern from the auto-route allowlist.
157
158```bash
159gordon autoroute allow remove <pattern>
160gordon autoroute allow remove example.com
161gordon autoroute allow remove example.com --remote https://gordon.mydomain.com --token $TOKEN
162```
163
164### Arguments
165
166| Argument | Description |
167|----------|-------------|
168| `<pattern>` | Domain pattern to remove from the allowlist |
169
170### Options
171
172| Option | Description |
173|--------|-------------|
174| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
175| `--token` | Authentication token for remote |
176
177### Description
178
179Removes an exact allowlist entry.
180Use the same pattern string you added, including the `*.` prefix for wildcard entries.
181
182### Examples
183
184```bash
185# Remove an exact domain
186gordon autoroute allow remove example.com
187
188# Remove a wildcard domain
189gordon autoroute allow remove "*.staging.example.com"
190
191# Remote (override)
192gordon autoroute allow remove example.com --remote https://gordon.mydomain.com --token $TOKEN
193```
194
195### Output
196
197```text
198✓ Allowed domain removed
199```
200
201## Related
202
203- [CLI Overview](./index.md)
204- [Routes Command](./routes.md)
205- [Config Command](./config.md)