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:

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:

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- You have a pre-generated token from `gordon auth token generate`
199- You want to update an expired token
200
201### Examples
202
203```bash
204# Set token for prod remote
205gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
206
207# Set token from file
208gordon remotes set-token staging $(cat token.txt)
209
210# Set token from environment variable
211gordon remotes set-token prod "$GORDON_TOKEN"
212```
213
214### Output
215
216```
217✓ Token updated for remote 'prod'
218```
219
220---
221
222## Configuration File
223
224Remotes are stored in `~/.config/gordon/remotes.toml`:
225
226```toml
227active = "prod"
228
229[remotes.prod]
230url = "https://gordon.mydomain.com"
231token_env = "PROD_TOKEN"
232insecure_tls = true
233
234[remotes.staging]
235url = "https://staging.mydomain.com"
236token = "eyJ..."
237```
238
239## Resolution Precedence
240
241When multiple sources specify remote or token, the CLI uses this priority:
242
243**Remote URL:**
2441. `--remote` flag
2452. `GORDON_REMOTE` environment variable
2463. Active remote from `remotes.toml`
247
248**Token:**
2491. `--token` flag
2502. `GORDON_TOKEN` environment variable
2513. Token from client config (`gordon.toml`)
2524. `pass` store (`gordon/remotes/<name>/token`)
2535. Token from active remote in `remotes.toml`
254
255**Insecure TLS:**
2561. `--insecure` flag
2572. `GORDON_INSECURE` environment variable (`true`/`false`)
2583. `[client] insecure_tls` in `gordon.toml`
2594. `insecure_tls` from the selected remote in `remotes.toml`
260
261This allows overriding specific values while keeping defaults:
262
263```bash
264# Active remote is prod, but use different token
265gordon routes list --token $TEMPORARY_TOKEN
266```
267
268---
269
270## Workflow Examples
271
272### Multi-Environment Setup
273
274```bash
275# Add all environments
276gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
277gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
278gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
279
280# Work with prod
281gordon remotes use prod
282gordon routes list
283gordon secrets list myapp.example.com
284
285# Switch to staging
286gordon remotes use staging
287gordon routes list
288```
289
290### CI/CD Pipeline
291
292```yaml
293# GitHub Actions example
294env:
295  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
296  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
297
298steps:
299  - name: Deploy to Gordon
300    run: |
301      gordon routes deploy myapp.example.com
302```
303
304### Compare Environments
305
306```bash
307# Compare routes across environments
308gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
309gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
310
311# Or switch between active remotes
312gordon remotes use prod && gordon routes list
313gordon remotes use staging && gordon routes list
314```
315
316### Private Admin + Wildcard App Domains
317
318Recommended default: use your normal Gordon admin domain with a valid public certificate.
319
320```toml
321# ~/.config/gordon/remotes.toml
322active = "prod"
323
324[remotes.prod]
325url = "https://gordon.example.com"
326token_env = "GORDON_TOKEN"
327```
328
329If your admin/API path is private over Tailscale, you have two options:
330
3311. Use `insecure_tls = true` for that remote.
3322. Prefer a Tailscale-issued cert on the machine's `*.ts.net` name and keep verification enabled.
333
334Tailscale 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:
335
336```bash
337sudo tailscale cert --cert-file /etc/gordon/tls/cert.pem --key-file /etc/gordon/tls/key.pem host-name.tailnet.ts.net
338```
339
340Configure Gordon to use them:
341
342```toml
343[server]
344tls_enabled = true
345tls_port = 443
346tls_cert_file = "/etc/gordon/tls/cert.pem"
347tls_key_file = "/etc/gordon/tls/key.pem"
348```
349
350`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`.
351
352## Related
353
354- [CLI Overview](./index.md)
355- [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