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.

If no remote is active and you do not pass --remote, Gordon can also auto-infer a saved remote for commands with a concrete target (for example gordon push myapp, gordon deploy app.example.com, or gordon images tags myapp). It only auto-selects when exactly one saved remote matches. Ambiguous matches and probe failures require an explicit --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. Auto-inference is not used for those aggregate views.

Remote target selection:

--remote flag
GORDON_REMOTE environment variable
Active remote from remotes.toml
Auto-inferred saved remote for supported target-based commands

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