remotes.md Raw History Folder

Remotes Commands

Manage saved remote Gordon instances for easier CLI usage.

gordon remotes

Subcommands

Subcommand	Description
`list`	List saved remotes
`add`	Add a new remote
`remove`	Remove a saved remote
`use`	Set active remote
`set-token`	Set or update token for a remote

gordon remotes list

List all saved remotes.

gordon remotes list

Output

Saved Remotes

Name            URL                                    Token           Status
-------------------------------------------------------------------------------
prod            https://gordon.mydomain.com            $PROD_TOKEN     active
staging         https://staging.mydomain.com           set
dev             https://dev.mydomain.com               none

gordon remotes add

Add a new remote.

gordon remotes add <name> <url> [options]

Arguments

Argument	Description
`<name>`	Name for the remote (e.g., `prod`, `staging`)
`<url>`	Gordon URL (the `gordon_domain` from remote config)

Note: <url> must match the configured gordon_domain. Older servers that only set registry_domain may need a config migration before remote CLI works.

Options

Option	Description
`--token`	Store token directly in config
`--token-env`	Store environment variable name (token resolved at runtime)
`--insecure`	Skip TLS certificate verification for this remote

Examples

# Basic (no token)
gordon remotes add prod https://gordon.mydomain.com

# With direct token
gordon remotes add prod https://gordon.mydomain.com --token eyJ...

# With environment variable reference (recommended)
gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN

# With self-signed certificate
gordon remotes add dev https://dev.internal --insecure

Token Security

Option 1: pass Store (Recommended)

When pass 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.

Tokens 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.

Option 2: Environment Variable Reference

gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN

The remotes.toml stores only the variable name:

[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"

At runtime, Gordon reads $PROD_TOKEN from the environment.

Option 3: Direct Token Storage

gordon remotes add prod https://gordon.mydomain.com --token eyJ...

The token is stored directly in ~/.config/gordon/remotes.toml. Ensure restricted permissions:

chmod 600 ~/.config/gordon/remotes.toml

gordon remotes remove

Remove a saved remote.

gordon remotes remove <name>
gordon remotes remove <name> --force  # Skip confirmation

Arguments

Argument	Description
`<name>`	Name of the remote to remove

Options

Option	Description
`--force`	Skip confirmation prompt

Example

gordon remotes remove staging

gordon remotes use

Set the active remote.

gordon remotes use <name>

Arguments

Argument	Description
`<name>`	Name of the remote to set as active

Description

When a remote is active, it's used automatically for most remote-capable commands without needing to specify --remote and --token. gordon routes list and gordon routes status are the exception: they aggregate local + saved remotes unless you set --remote or GORDON_REMOTE.

gordon remotes use prod
gordon secrets list app.com     # Uses prod remote automatically
gordon routes list              # Aggregates local + saved remotes
gordon routes status            # Aggregates local + saved remotes

Example

gordon remotes use prod

gordon remotes set-token

Set or update the authentication token for a saved remote.

gordon remotes set-token <name> <token>

Arguments

Argument	Description
`<name>`	Name of the remote
`<token>`	The JWT token to set

Description

This command is useful when:

You have a pre-generated token from gordon auth token generate
You want to update an expired token

Examples

# Set token for prod remote
gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...

# Set token from file
gordon remotes set-token staging $(cat token.txt)

# Set token from environment variable
gordon remotes set-token prod "$GORDON_TOKEN"

Output

✓ Token updated for remote 'prod'

Configuration File

Remotes are stored in ~/.config/gordon/remotes.toml:

active = "prod"

[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"
insecure_tls = true

[remotes.staging]
url = "https://staging.mydomain.com"
token = "eyJ..."

Resolution Precedence

When multiple sources specify remote or token, the CLI uses this priority:

For routes list and routes status, --remote and GORDON_REMOTE are the explicit single-target selectors. Without either one, those commands aggregate local + saved remotes even when an active remote exists.

Remote URL:

--remote flag
GORDON_REMOTE environment variable
Active remote from remotes.toml

Token:

--token flag
GORDON_TOKEN environment variable
Token from client config (gordon.toml)
pass store (gordon/remotes/<name>/token)
Token from active remote in remotes.toml

Insecure TLS:

--insecure flag
GORDON_INSECURE environment variable (true/false)
[client] insecure_tls in gordon.toml
insecure_tls from the selected remote in remotes.toml

This allows overriding specific values while keeping defaults:

# Aggregate routes views
gordon routes list
gordon routes status

# Force one target
GORDON_REMOTE=prod gordon routes list
GORDON_REMOTE=prod gordon routes status

Workflow Examples

Multi-Environment Setup

# Add all environments
gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN

# Work with prod
gordon remotes use prod
gordon secrets list myapp.example.com
gordon routes list --remote prod

# Switch to staging
gordon remotes use staging
GORDON_REMOTE=staging gordon routes status

CI/CD Pipeline

# GitHub Actions example
env:
  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}

steps:
  - name: Deploy to Gordon
    run: |
      gordon routes deploy myapp.example.com

Compare Environments

# Aggregate route inventory/status across local + saved remotes
gordon routes list
gordon routes status

# Compare one target at a time
gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
GORDON_REMOTE=staging gordon routes status

# Or switch between active remotes for other commands
gordon remotes use prod && gordon secrets list myapp.example.com
gordon remotes use staging && gordon secrets list myapp.example.com

Private Admin + Wildcard App Domains

Recommended default: use your normal Gordon admin domain with a valid public certificate.

# ~/.config/gordon/remotes.toml
active = "prod"

[remotes.prod]
url = "https://gordon.example.com"
token_env = "GORDON_TOKEN"

A 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:

insecure_tls = true on the remote — skips certificate verification entirely
sudo gordon ca install — installs the root CA into system, Firefox, and Java trust stores
gordon ca export --out gordon-ca.crt — exports the root CA PEM for manual installation
Visit https://<gordon-host>:<tls_port>/ca in a browser — onboarding page with downloads for macOS, Linux, Windows, iOS, and Android

If 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. The static cert is served for SNI-matching domains; everything else falls through to the internal CA.

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.

Migration from [client] Config

The [client] section in gordon.toml is deprecated. On first run, Gordon auto-migrates it to a default remote entry in remotes.toml and sets it as active. No manual action needed.

source

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 most remote-capable commands without needing to specify `--remote` and `--token`.
166`gordon routes list` and `gordon routes status` are the exception: they aggregate local + saved remotes unless you set `--remote` or `GORDON_REMOTE`.
167
168```bash
169gordon remotes use prod
170gordon secrets list app.com     # Uses prod remote automatically
171gordon routes list              # Aggregates local + saved remotes
172gordon routes status            # Aggregates local + saved remotes
173```
174
175### Example
176
177```bash
178gordon remotes use prod
179```
180
181---
182
183## gordon remotes set-token
184
185Set or update the authentication token for a saved remote.
186
187```bash
188gordon remotes set-token <name> <token>
189```
190
191### Arguments
192
193| Argument | Description |
194|----------|-------------|
195| `<name>` | Name of the remote |
196| `<token>` | The JWT token to set |
197
198### Description
199
200This command is useful when:
201
202- You have a pre-generated token from `gordon auth token generate`
203- You want to update an expired token
204
205### Examples
206
207```bash
208# Set token for prod remote
209gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
210
211# Set token from file
212gordon remotes set-token staging $(cat token.txt)
213
214# Set token from environment variable
215gordon remotes set-token prod "$GORDON_TOKEN"
216```
217
218### Output
219
220```
221✓ Token updated for remote 'prod'
222```
223
224---
225
226## Configuration File
227
228Remotes are stored in `~/.config/gordon/remotes.toml`:
229
230```toml
231active = "prod"
232
233[remotes.prod]
234url = "https://gordon.mydomain.com"
235token_env = "PROD_TOKEN"
236insecure_tls = true
237
238[remotes.staging]
239url = "https://staging.mydomain.com"
240token = "eyJ..."
241```
242
243## Resolution Precedence
244
245When multiple sources specify remote or token, the CLI uses this priority:
246
247For `routes list` and `routes status`, `--remote` and `GORDON_REMOTE` are the explicit single-target selectors. Without either one, those commands aggregate local + saved remotes even when an active remote exists.
248
249**Remote URL:**
2501. `--remote` flag
2512. `GORDON_REMOTE` environment variable
2523. Active remote from `remotes.toml`
253
254**Token:**
2551. `--token` flag
2562. `GORDON_TOKEN` environment variable
2573. Token from client config (`gordon.toml`)
2584. `pass` store (`gordon/remotes/<name>/token`)
2595. Token from active remote in `remotes.toml`
260
261**Insecure TLS:**
2621. `--insecure` flag
2632. `GORDON_INSECURE` environment variable (`true`/`false`)
2643. `[client] insecure_tls` in `gordon.toml`
2654. `insecure_tls` from the selected remote in `remotes.toml`
266
267This allows overriding specific values while keeping defaults:
268
269```bash
270# Aggregate routes views
271gordon routes list
272gordon routes status
273
274# Force one target
275GORDON_REMOTE=prod gordon routes list
276GORDON_REMOTE=prod gordon routes status
277```
278
279---
280
281## Workflow Examples
282
283### Multi-Environment Setup
284
285```bash
286# Add all environments
287gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
288gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
289gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
290
291# Work with prod
292gordon remotes use prod
293gordon secrets list myapp.example.com
294gordon routes list --remote prod
295
296# Switch to staging
297gordon remotes use staging
298GORDON_REMOTE=staging gordon routes status
299```
300
301### CI/CD Pipeline
302
303```yaml
304# GitHub Actions example
305env:
306  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
307  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
308
309steps:
310  - name: Deploy to Gordon
311    run: |
312      gordon routes deploy myapp.example.com
313```
314
315### Compare Environments
316
317```bash
318# Aggregate route inventory/status across local + saved remotes
319gordon routes list
320gordon routes status
321
322# Compare one target at a time
323gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
324GORDON_REMOTE=staging gordon routes status
325
326# Or switch between active remotes for other commands
327gordon remotes use prod && gordon secrets list myapp.example.com
328gordon remotes use staging && gordon secrets list myapp.example.com
329```
330
331### Private Admin + Wildcard App Domains
332
333Recommended default: use your normal Gordon admin domain with a valid public certificate.
334
335```toml
336# ~/.config/gordon/remotes.toml
337active = "prod"
338
339[remotes.prod]
340url = "https://gordon.example.com"
341token_env = "GORDON_TOKEN"
342```
343
344A 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:
345
346- `insecure_tls = true` on the remote — skips certificate verification entirely
347- `sudo gordon ca install` — installs the root CA into system, Firefox, and Java trust stores
348- `gordon ca export --out gordon-ca.crt` — exports the root CA PEM for manual installation
349- Visit `https://<gordon-host>:<tls_port>/ca` in a browser — onboarding page with downloads for macOS, Linux, Windows, iOS, and Android
350
351If 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.
352
353`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`.
354
355## Migration from [client] Config
356
357The `[client]` section in `gordon.toml` is deprecated. On first run, Gordon
358auto-migrates it to a `default` remote entry in `remotes.toml` and sets it
359as active. No manual action needed.
360
361## Related
362
363- [CLI Overview](./index.md)
364- [Remote CLI Guide](/wiki/guides/remote-cli.md)

remotes.md RawHistoryFolder

Remotes Commands

gordon remotes

Subcommands

gordon remotes list

Output

gordon remotes add

Arguments

Options

Examples

Token Security

gordon remotes remove

Arguments

Options

Example

gordon remotes use

Arguments

Description

Example

gordon remotes set-token

Arguments

Description

Examples

Output

Configuration File

Resolution Precedence

Workflow Examples

Multi-Environment Setup

CI/CD Pipeline

Compare Environments

Private Admin + Wildcard App Domains

Migration from [client] Config

Related

remotes.md Raw History Folder