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)

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 all remote-capable commands without needing to specify --remote and --token:

gordon remotes use prod
gordon routes list              # Uses prod remote automatically
gordon secrets list app.com     # Uses prod remote automatically

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:

The server uses token-based authentication (not password auth)
You have a pre-generated token from gordon auth token generate
You want to update an expired token

For servers with password authentication, use gordon auth login instead.

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:

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:

# Active remote is prod, but use different token
gordon routes list --token $TEMPORARY_TOKEN

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 routes list
gordon secrets list myapp.example.com

# Switch to staging
gordon remotes use staging
gordon routes list

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

# Compare routes across environments
gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN

# Or switch between active remotes
gordon remotes use prod && gordon routes list
gordon remotes use staging && gordon routes list

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"

If your admin/API path is private over Tailscale, you have two options:

Use insecure_tls = true for that remote.
Prefer a Tailscale-issued cert on the machine's *.ts.net name and keep verification enabled.

Tailscale certificates are issued for tailnet MagicDNS names (for example host-name.tailnet.ts.net), not your custom domain. Enable HTTPS certificates in the Tailscale admin DNS settings, then generate files on the host:

sudo tailscale cert --cert-file /etc/gordon/tls/cert.pem --key-file /etc/gordon/tls/key.pem host-name.tailnet.ts.net

Configure Gordon to use them:

[server]
tls_enabled = true
tls_port = 443
tls_cert_file = "/etc/gordon/tls/cert.pem"
tls_key_file = "/etc/gordon/tls/key.pem"

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.

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### Options
57
58| Option | Description |
59|--------|-------------|
60| `--token` | Store token directly in config |
61| `--token-env` | Store environment variable name (token resolved at runtime) |
62| `--insecure` | Skip TLS certificate verification for this remote |
63
64### Examples
65
66```bash
67# Basic (no token)
68gordon remotes add prod https://gordon.mydomain.com
69
70# With direct token
71gordon remotes add prod https://gordon.mydomain.com --token eyJ...
72
73# With environment variable reference (recommended)
74gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
75
76# With self-signed certificate
77gordon remotes add dev https://dev.internal --insecure
78```
79
80### Token Security
81
82**Option 1: pass Store (Recommended)**
83
84When [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.
85
86Tokens 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.
87
88**Option 2: Environment Variable Reference**
89
90```bash
91gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
92```
93
94The `remotes.toml` stores only the variable name:
95
96```toml
97[remotes.prod]
98url = "https://gordon.mydomain.com"
99token_env = "PROD_TOKEN"
100```
101
102At runtime, Gordon reads `$PROD_TOKEN` from the environment.
103
104**Option 3: Direct Token Storage**
105
106```bash
107gordon remotes add prod https://gordon.mydomain.com --token eyJ...
108```
109
110The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
111
112```bash
113chmod 600 ~/.config/gordon/remotes.toml
114```
115
116---
117
118## gordon remotes remove
119
120Remove a saved remote.
121
122```bash
123gordon remotes remove <name>
124gordon remotes remove <name> --force  # Skip confirmation
125```
126
127### Arguments
128
129| Argument | Description |
130|----------|-------------|
131| `<name>` | Name of the remote to remove |
132
133### Options
134
135| Option | Description |
136|--------|-------------|
137| `--force` | Skip confirmation prompt |
138
139### Example
140
141```bash
142gordon remotes remove staging
143```
144
145---
146
147## gordon remotes use
148
149Set the active remote.
150
151```bash
152gordon remotes use <name>
153```
154
155### Arguments
156
157| Argument | Description |
158|----------|-------------|
159| `<name>` | Name of the remote to set as active |
160
161### Description
162
163When a remote is active, it's used automatically for all remote-capable commands without needing to specify `--remote` and `--token`:
164
165```bash
166gordon remotes use prod
167gordon routes list              # Uses prod remote automatically
168gordon secrets list app.com     # Uses prod remote automatically
169```
170
171### Example
172
173```bash
174gordon remotes use prod
175```
176
177---
178
179## gordon remotes set-token
180
181Set or update the authentication token for a saved remote.
182
183```bash
184gordon remotes set-token <name> <token>
185```
186
187### Arguments
188
189| Argument | Description |
190|----------|-------------|
191| `<name>` | Name of the remote |
192| `<token>` | The JWT token to set |
193
194### Description
195
196This command is useful when:
197
198- The server uses token-based authentication (not password auth)
199- You have a pre-generated token from `gordon auth token generate`
200- You want to update an expired token
201
202For servers with password authentication, use `gordon auth login` instead.
203
204### Examples
205
206```bash
207# Set token for prod remote
208gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
209
210# Set token from file
211gordon remotes set-token staging $(cat token.txt)
212
213# Set token from environment variable
214gordon remotes set-token prod "$GORDON_TOKEN"
215```
216
217### Output
218
219```
220✓ Token updated for remote 'prod'
221```
222
223---
224
225## Configuration File
226
227Remotes are stored in `~/.config/gordon/remotes.toml`:
228
229```toml
230active = "prod"
231
232[remotes.prod]
233url = "https://gordon.mydomain.com"
234token_env = "PROD_TOKEN"
235insecure_tls = true
236
237[remotes.staging]
238url = "https://staging.mydomain.com"
239token = "eyJ..."
240```
241
242## Resolution Precedence
243
244When multiple sources specify remote or token, the CLI uses this priority:
245
246**Remote URL:**
2471. `--remote` flag
2482. `GORDON_REMOTE` environment variable
2493. Active remote from `remotes.toml`
250
251**Token:**
2521. `--token` flag
2532. `GORDON_TOKEN` environment variable
2543. Token from client config (`gordon.toml`)
2554. `pass` store (`gordon/remotes/<name>/token`)
2565. Token from active remote in `remotes.toml`
257
258**Insecure TLS:**
2591. `--insecure` flag
2602. `GORDON_INSECURE` environment variable (`true`/`false`)
2613. `[client] insecure_tls` in `gordon.toml`
2624. `insecure_tls` from the selected remote in `remotes.toml`
263
264This allows overriding specific values while keeping defaults:
265
266```bash
267# Active remote is prod, but use different token
268gordon routes list --token $TEMPORARY_TOKEN
269```
270
271---
272
273## Workflow Examples
274
275### Multi-Environment Setup
276
277```bash
278# Add all environments
279gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
280gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
281gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
282
283# Work with prod
284gordon remotes use prod
285gordon routes list
286gordon secrets list myapp.example.com
287
288# Switch to staging
289gordon remotes use staging
290gordon routes list
291```
292
293### CI/CD Pipeline
294
295```yaml
296# GitHub Actions example
297env:
298  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
299  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
300
301steps:
302  - name: Deploy to Gordon
303    run: |
304      gordon routes deploy myapp.example.com
305```
306
307### Compare Environments
308
309```bash
310# Compare routes across environments
311gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
312gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
313
314# Or switch between active remotes
315gordon remotes use prod && gordon routes list
316gordon remotes use staging && gordon routes list
317```
318
319### Private Admin + Wildcard App Domains
320
321Recommended default: use your normal Gordon admin domain with a valid public certificate.
322
323```toml
324# ~/.config/gordon/remotes.toml
325active = "prod"
326
327[remotes.prod]
328url = "https://gordon.example.com"
329token_env = "GORDON_TOKEN"
330```
331
332If your admin/API path is private over Tailscale, you have two options:
333
3341. Use `insecure_tls = true` for that remote.
3352. Prefer a Tailscale-issued cert on the machine's `*.ts.net` name and keep verification enabled.
336
337Tailscale certificates are issued for tailnet MagicDNS names (for example `host-name.tailnet.ts.net`), not your custom domain. Enable HTTPS certificates in the Tailscale admin DNS settings, then generate files on the host:
338
339```bash
340sudo tailscale cert --cert-file /etc/gordon/tls/cert.pem --key-file /etc/gordon/tls/key.pem host-name.tailnet.ts.net
341```
342
343Configure Gordon to use them:
344
345```toml
346[server]
347tls_enabled = true
348tls_port = 443
349tls_cert_file = "/etc/gordon/tls/cert.pem"
350tls_key_file = "/etc/gordon/tls/key.pem"
351```
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## Related
356
357- [CLI Overview](./index.md)
358- [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

Related

remotes.md Raw History Folder