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: Environment Variable Reference (Recommended)

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