1# Remotes Commands
2
3Manage saved remote Gordon instances for easier CLI usage.
4
5## gordon remotes
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `list` | List saved remotes |
12| `add` | Add a new remote |
13| `remove` | Remove a saved remote |
14| `use` | Set active remote |
15| `set-token` | Set or update token for a remote |
16
17---
18
19## gordon remotes list
20
21List all saved remotes.
22
23```bash
24gordon remotes list
25```
26
27### Output
28
29```
30Saved Remotes
31
32Name            URL                                    Token           Status
33-------------------------------------------------------------------------------
34prod            https://gordon.mydomain.com            $PROD_TOKEN     active
35staging         https://staging.mydomain.com           set
36dev             https://dev.mydomain.com               none
37```
38
39---
40
41## gordon remotes add
42
43Add a new remote.
44
45```bash
46gordon remotes add <name> <url> [options]
47```
48
49### Arguments
50
51| Argument | Description |
52|----------|-------------|
53| `<name>` | Name for the remote (e.g., `prod`, `staging`) |
54| `<url>` | Gordon URL (the `gordon_domain` from remote config) |
55
56> **Note:** `<url>` must match the configured `gordon_domain`. Older servers that only set `registry_domain` may need a config migration before remote CLI works.
57
58### Options
59
60| Option | Description |
61|--------|-------------|
62| `--token` | Store token directly in config |
63| `--token-env` | Store environment variable name (token resolved at runtime) |
64| `--insecure` | Skip TLS certificate verification for this remote |
65
66### Examples
67
68```bash
69# Basic (no token)
70gordon remotes add prod https://gordon.mydomain.com
71
72# With direct token
73gordon remotes add prod https://gordon.mydomain.com --token eyJ...
74
75# With environment variable reference (recommended)
76gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
77
78# With self-signed certificate
79gordon remotes add dev https://dev.internal --insecure
80```
81
82### Token Security
83
84**Option 1: pass Store (Recommended)**
85
86When [pass](https://www.passwordstore.org/) is installed and initialized, Gordon stores tokens encrypted via GPG automatically. No extra flags are needed -- `gordon auth login` and `gordon remotes set-token` use `pass` when available.
87
88Tokens are stored at the path `gordon/remotes/<name>/token` inside the pass store. If `pass` is unavailable, Gordon falls back to plaintext config with a warning.
89
90**Option 2: Environment Variable Reference**
91
92```bash
93gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
94```
95
96The `remotes.toml` stores only the variable name:
97
98```toml
99[remotes.prod]
100url = "https://gordon.mydomain.com"
101token_env = "PROD_TOKEN"
102```
103
104At runtime, Gordon reads `$PROD_TOKEN` from the environment.
105
106**Option 3: Direct Token Storage**
107
108```bash
109gordon remotes add prod https://gordon.mydomain.com --token eyJ...
110```
111
112The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
113
114```bash
115chmod 600 ~/.config/gordon/remotes.toml
116```
117
118---
119
120## gordon remotes remove
121
122Remove a saved remote.
123
124```bash
125gordon remotes remove <name>
126gordon remotes remove <name> --force  # Skip confirmation
127```
128
129### Arguments
130
131| Argument | Description |
132|----------|-------------|
133| `<name>` | Name of the remote to remove |
134
135### Options
136
137| Option | Description |
138|--------|-------------|
139| `--force` | Skip confirmation prompt |
140
141### Example
142
143```bash
144gordon remotes remove staging
145```
146
147---
148
149## gordon remotes use
150
151Set the active remote.
152
153```bash
154gordon remotes use <name>
155```
156
157### Arguments
158
159| Argument | Description |
160|----------|-------------|
161| `<name>` | Name of the remote to set as active |
162
163### Description
164
165When a remote is active, it's used automatically for all remote-capable commands without needing to specify `--remote` and `--token`:
166
167```bash
168gordon remotes use prod
169gordon routes list              # Uses prod remote automatically
170gordon secrets list app.com     # Uses prod remote automatically
171```
172
173### Example
174
175```bash
176gordon remotes use prod
177```
178
179---
180
181## gordon remotes set-token
182
183Set or update the authentication token for a saved remote.
184
185```bash
186gordon remotes set-token <name> <token>
187```
188
189### Arguments
190
191| Argument | Description |
192|----------|-------------|
193| `<name>` | Name of the remote |
194| `<token>` | The JWT token to set |
195
196### Description
197
198This command is useful when:
199
200- You have a pre-generated token from `gordon auth token generate`
201- You want to update an expired token
202
203### Examples
204
205```bash
206# Set token for prod remote
207gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
208
209# Set token from file
210gordon remotes set-token staging $(cat token.txt)
211
212# Set token from environment variable
213gordon remotes set-token prod "$GORDON_TOKEN"
214```
215
216### Output
217
218```
219✓ Token updated for remote 'prod'
220```
221
222---
223
224## Configuration File
225
226Remotes are stored in `~/.config/gordon/remotes.toml`:
227
228```toml
229active = "prod"
230
231[remotes.prod]
232url = "https://gordon.mydomain.com"
233token_env = "PROD_TOKEN"
234insecure_tls = true
235
236[remotes.staging]
237url = "https://staging.mydomain.com"
238token = "eyJ..."
239```
240
241## Resolution Precedence
242
243When multiple sources specify remote or token, the CLI uses this priority:
244
245**Remote URL:**
2461. `--remote` flag
2472. `GORDON_REMOTE` environment variable
2483. Active remote from `remotes.toml`
249
250**Token:**
2511. `--token` flag
2522. `GORDON_TOKEN` environment variable
2533. Token from client config (`gordon.toml`)
2544. `pass` store (`gordon/remotes/<name>/token`)
2555. Token from active remote in `remotes.toml`
256
257**Insecure TLS:**
2581. `--insecure` flag
2592. `GORDON_INSECURE` environment variable (`true`/`false`)
2603. `[client] insecure_tls` in `gordon.toml`
2614. `insecure_tls` from the selected remote in `remotes.toml`
262
263This allows overriding specific values while keeping defaults:
264
265```bash
266# Active remote is prod, but use different token
267gordon routes list --token $TEMPORARY_TOKEN
268```
269
270---
271
272## Workflow Examples
273
274### Multi-Environment Setup
275
276```bash
277# Add all environments
278gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
279gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
280gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
281
282# Work with prod
283gordon remotes use prod
284gordon routes list
285gordon secrets list myapp.example.com
286
287# Switch to staging
288gordon remotes use staging
289gordon routes list
290```
291
292### CI/CD Pipeline
293
294```yaml
295# GitHub Actions example
296env:
297  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
298  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
299
300steps:
301  - name: Deploy to Gordon
302    run: |
303      gordon routes deploy myapp.example.com
304```
305
306### Compare Environments
307
308```bash
309# Compare routes across environments
310gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
311gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
312
313# Or switch between active remotes
314gordon remotes use prod && gordon routes list
315gordon remotes use staging && gordon routes list
316```
317
318### Private Admin + Wildcard App Domains
319
320Recommended default: use your normal Gordon admin domain with a valid public certificate.
321
322```toml
323# ~/.config/gordon/remotes.toml
324active = "prod"
325
326[remotes.prod]
327url = "https://gordon.example.com"
328token_env = "GORDON_TOKEN"
329```
330
331A common Tailscale setup is to point your domain's DNS at the machine's Tailscale IP (Cloudflare DNS-only / grey cloud). Since the server isn't publicly reachable, there is no external CA to issue a trusted certificate — Gordon's internal CA handles TLS automatically. Clients need to trust the internal CA:
332
333- `insecure_tls = true` on the remote — skips certificate verification entirely
334- `sudo gordon ca install` — installs the root CA into system, Firefox, and Java trust stores
335- `gordon ca export --out gordon-ca.crt` — exports the root CA PEM for manual installation
336- Visit `https://<gordon-host>:<tls_port>/ca` in a browser — onboarding page with downloads for macOS, Linux, Windows, iOS, and Android
337
338If you have your own certificate for the domain (e.g. from a corporate CA), you can provide it via `tls_cert_file`/`tls_key_file` — see [Server Configuration](../config/server.md#custom-certificates). The static cert is served for SNI-matching domains; everything else falls through to the internal CA.
339
340`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change runtime routing: Gordon reverse proxy and container routes can still serve wildcard app domains like `*.example.com`.
341
342## Migration from [client] Config
343
344The `[client]` section in `gordon.toml` is deprecated. On first run, Gordon
345auto-migrates it to a `default` remote entry in `remotes.toml` and sets it
346as active. No manual action needed.
347
348## Related
349
350- [CLI Overview](./index.md)
351- [Remote CLI Guide](/wiki/guides/remote-cli.md)