remote-cli.md Raw History Folder

Remote CLI Management

Manage Gordon instances remotely using the CLI with the --remote flag or saved remotes.

What You'll Learn

Using global --remote and --token flags
Saving and managing remote connections
Environment variable configuration
Token security best practices
Remote command workflows

Prerequisites

Gordon CLI installed
A remote Gordon instance running with admin API enabled
Authentication token for the remote instance

Understanding the Remote URL

The --remote URL must be the gordon_domain configured on the remote Gordon instance. This domain serves both the container registry and the Admin API.

# On the remote Gordon server
[server]
gordon_domain = "gordon.example.com"  # Use this as --remote URL

The CLI connects to https://gordon.example.com/admin/* endpoints.

Quick Start

One-off Remote Command

gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

Using Environment Variables

export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=$TOKEN
gordon routes list

Using Saved Remotes

# Add a remote
gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN

# Set as active
gordon remotes use prod

# Now use without flags
gordon routes list

Global Flags

These flags are available on all commands:

Flag	Description
`--remote <URL>`	Remote Gordon URL
`--token <TOKEN>`	Authentication token

# List routes on remote
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

# Manage secrets on remote
gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN

Environment Variables

Variable	Description
`GORDON_REMOTE`	Remote Gordon URL
`GORDON_TOKEN`	Authentication token

Environment variables are useful for CI/CD pipelines and shell sessions:

# Set for current session
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Commands automatically use these
gordon routes list
gordon secrets list myapp.example.com

Saved Remotes

Save frequently used remotes to avoid repeating URLs and tokens.

Configuration File

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

active = "prod"

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

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

Managing Remotes

List 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

Add a Remote

# 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

Flag	Description
`--token <TOKEN>`	Store token directly in config
`--token-env <VAR>`	Store env variable name (token resolved at runtime)

Remove a Remote

# With confirmation prompt
gordon remotes remove staging

# Skip confirmation
gordon remotes remove staging --force

Set Active Remote

gordon remotes use prod

When a remote is active, it's used automatically for all remote-capable commands:

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

Resolution Precedence

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

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

This allows overriding specific values while keeping defaults:

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

Commands Supporting Remote

These commands work with remote targeting:

Command	Description
`gordon routes list`	List all routes
`gordon routes add <domain> <image>`	Add a route
`gordon routes remove <domain>`	Remove a route
`gordon routes deploy <domain>`	Deploy/redeploy a route
`gordon secrets list <domain>`	List secrets for a domain
`gordon secrets set <domain> KEY=value`	Set secrets
`gordon secrets remove <domain> <key>`	Remove a secret
`gordon status`	Show server status

Token Security

Option 1: Environment Variable Reference (Recommended)

Store the environment variable name, not the actual token:

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

The remotes.toml stores only:

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

At runtime, Gordon reads $PROD_TOKEN from the environment.

Benefits:

Token not stored in plaintext config
Works with secret managers that inject env vars
Easy rotation without editing config

Option 2: Direct Token Storage

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

The token is stored directly in remotes.toml:

[remotes.prod]
url = "https://gordon.mydomain.com"
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Security note: Ensure remotes.toml has restricted permissions:

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

Option 3: Environment Variables Only

For maximum security, don't save tokens at all:

# Add remote without token
gordon remotes add prod https://gordon.mydomain.com

# Set token via environment
export GORDON_TOKEN=$TOKEN

# Use normally
gordon remotes use prod
gordon routes list

Workflow Examples

Development Workflow

# Add dev and staging remotes
gordon remotes add dev https://gordon.dev.local --token-env DEV_TOKEN
gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN

# Work with dev
gordon remotes use dev
gordon routes list
gordon routes add myapp.dev.local myapp:latest

# 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

# GitLab CI example
deploy:
  script:
    - export GORDON_REMOTE=$GORDON_URL
    - export GORDON_TOKEN=$GORDON_TOKEN
    - gordon routes deploy myapp.example.com

Multi-Environment Management

# 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

# 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 active
gordon remotes use prod && gordon routes list
gordon remotes use staging && gordon routes list

Troubleshooting

"unauthorized" Error

Token is missing, expired, or invalid.

# Check if token is set
echo $GORDON_TOKEN

# Verify token works
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

"connection refused" Error

Remote Gordon isn't running or URL is wrong.

# Verify URL is correct
curl https://gordon.mydomain.com/health

# Check if admin API is enabled on remote
# The remote gordon.toml needs:
# [admin]
# enabled = true

Remote Not Found

The specified remote doesn't exist in remotes.toml.

# List available remotes
gordon remotes list

# Add the remote
gordon remotes add myremote https://gordon.mydomain.com

Active Remote Cleared

After removing the active remote, you need to set a new active:

gordon remotes use prod

Or use explicit flags:

gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

source

1# Remote CLI Management
2
3Manage Gordon instances remotely using the CLI with the `--remote` flag or saved remotes.
4
5## What You'll Learn
6
7- Using global `--remote` and `--token` flags
8- Saving and managing remote connections
9- Environment variable configuration
10- Token security best practices
11- Remote command workflows
12
13## Prerequisites
14
15- Gordon CLI installed
16- A remote Gordon instance running with admin API enabled
17- Authentication token for the remote instance
18
19## Understanding the Remote URL
20
21The `--remote` URL must be the `gordon_domain` configured on the remote Gordon instance. This domain serves both the container registry and the Admin API.
22
23```toml
24# On the remote Gordon server
25[server]
26gordon_domain = "gordon.example.com"  # Use this as --remote URL
27```
28
29The CLI connects to `https://gordon.example.com/admin/*` endpoints.
30
31## Quick Start
32
33### One-off Remote Command
34
35```bash
36gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
37```
38
39### Using Environment Variables
40
41```bash
42export GORDON_REMOTE=https://gordon.mydomain.com
43export GORDON_TOKEN=$TOKEN
44gordon routes list
45```
46
47### Using Saved Remotes
48
49```bash
50# Add a remote
51gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
52
53# Set as active
54gordon remotes use prod
55
56# Now use without flags
57gordon routes list
58```
59
60## Global Flags
61
62These flags are available on all commands:
63
64| Flag | Description |
65|------|-------------|
66| `--remote <URL>` | Remote Gordon URL |
67| `--token <TOKEN>` | Authentication token |
68
69```bash
70# List routes on remote
71gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
72
73# Manage secrets on remote
74gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
75```
76
77## Environment Variables
78
79| Variable | Description |
80|----------|-------------|
81| `GORDON_REMOTE` | Remote Gordon URL |
82| `GORDON_TOKEN` | Authentication token |
83
84Environment variables are useful for CI/CD pipelines and shell sessions:
85
86```bash
87# Set for current session
88export GORDON_REMOTE=https://gordon.mydomain.com
89export GORDON_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
90
91# Commands automatically use these
92gordon routes list
93gordon secrets list myapp.example.com
94```
95
96## Saved Remotes
97
98Save frequently used remotes to avoid repeating URLs and tokens.
99
100### Configuration File
101
102Remotes are stored in `~/.config/gordon/remotes.toml`:
103
104```toml
105active = "prod"
106
107[remotes.prod]
108url = "https://gordon.mydomain.com"
109token_env = "PROD_TOKEN"
110
111[remotes.staging]
112url = "https://staging.mydomain.com"
113token = "eyJ..."
114```
115
116### Managing Remotes
117
118#### List Remotes
119
120```bash
121gordon remotes list
122```
123
124Output:
125
126```
127Saved Remotes
128
129Name            URL                                    Token           Status
130──────────────────────────────────────────────────────────────────────────────
131prod            https://gordon.mydomain.com            $PROD_TOKEN     active
132staging         https://staging.mydomain.com           set
133dev             https://dev.mydomain.com               none
134```
135
136#### Add a Remote
137
138```bash
139# Basic (no token)
140gordon remotes add prod https://gordon.mydomain.com
141
142# With direct token
143gordon remotes add prod https://gordon.mydomain.com --token eyJ...
144
145# With environment variable reference (recommended)
146gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
147```
148
149| Flag | Description |
150|------|-------------|
151| `--token <TOKEN>` | Store token directly in config |
152| `--token-env <VAR>` | Store env variable name (token resolved at runtime) |
153
154#### Remove a Remote
155
156```bash
157# With confirmation prompt
158gordon remotes remove staging
159
160# Skip confirmation
161gordon remotes remove staging --force
162```
163
164#### Set Active Remote
165
166```bash
167gordon remotes use prod
168```
169
170When a remote is active, it's used automatically for all remote-capable commands:
171
172```bash
173gordon remotes use prod
174gordon routes list              # Uses prod remote
175gordon secrets list app.com     # Uses prod remote
176```
177
178## Resolution Precedence
179
180When multiple sources specify remote or token, the CLI uses this priority order:
181
182**Remote URL:**
1831. `--remote` flag
1842. `GORDON_REMOTE` environment variable
1853. Active remote from `remotes.toml`
186
187**Token:**
1881. `--token` flag
1892. `GORDON_TOKEN` environment variable
1903. Token from active remote in `remotes.toml`
191
192This allows overriding specific values while keeping defaults:
193
194```bash
195# Active remote is prod, but use different token
196gordon routes list --token $TEMPORARY_TOKEN
197```
198
199## Commands Supporting Remote
200
201These commands work with remote targeting:
202
203| Command | Description |
204|---------|-------------|
205| `gordon routes list` | List all routes |
206| `gordon routes add <domain> <image>` | Add a route |
207| `gordon routes remove <domain>` | Remove a route |
208| `gordon routes deploy <domain>` | Deploy/redeploy a route |
209| `gordon secrets list <domain>` | List secrets for a domain |
210| `gordon secrets set <domain> KEY=value` | Set secrets |
211| `gordon secrets remove <domain> <key>` | Remove a secret |
212| `gordon status` | Show server status |
213
214## Token Security
215
216### Option 1: Environment Variable Reference (Recommended)
217
218Store the environment variable name, not the actual token:
219
220```bash
221gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
222```
223
224The `remotes.toml` stores only:
225
226```toml
227[remotes.prod]
228url = "https://gordon.mydomain.com"
229token_env = "PROD_TOKEN"
230```
231
232At runtime, Gordon reads `$PROD_TOKEN` from the environment.
233
234**Benefits:**
235- Token not stored in plaintext config
236- Works with secret managers that inject env vars
237- Easy rotation without editing config
238
239### Option 2: Direct Token Storage
240
241```bash
242gordon remotes add prod https://gordon.mydomain.com --token eyJ...
243```
244
245The token is stored directly in `remotes.toml`:
246
247```toml
248[remotes.prod]
249url = "https://gordon.mydomain.com"
250token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
251```
252
253**Security note:** Ensure `remotes.toml` has restricted permissions:
254
255```bash
256chmod 600 ~/.config/gordon/remotes.toml
257```
258
259### Option 3: Environment Variables Only
260
261For maximum security, don't save tokens at all:
262
263```bash
264# Add remote without token
265gordon remotes add prod https://gordon.mydomain.com
266
267# Set token via environment
268export GORDON_TOKEN=$TOKEN
269
270# Use normally
271gordon remotes use prod
272gordon routes list
273```
274
275## Workflow Examples
276
277### Development Workflow
278
279```bash
280# Add dev and staging remotes
281gordon remotes add dev https://gordon.dev.local --token-env DEV_TOKEN
282gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
283
284# Work with dev
285gordon remotes use dev
286gordon routes list
287gordon routes add myapp.dev.local myapp:latest
288
289# Switch to staging
290gordon remotes use staging
291gordon routes list
292```
293
294### CI/CD Pipeline
295
296```yaml
297# GitHub Actions example
298env:
299  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
300  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
301
302steps:
303  - name: Deploy to Gordon
304    run: |
305      gordon routes deploy myapp.example.com
306```
307
308```bash
309# GitLab CI example
310deploy:
311  script:
312    - export GORDON_REMOTE=$GORDON_URL
313    - export GORDON_TOKEN=$GORDON_TOKEN
314    - gordon routes deploy myapp.example.com
315```
316
317### Multi-Environment Management
318
319```bash
320# Add all environments
321gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
322gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
323gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
324
325# Compare routes across environments
326gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
327gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
328
329# Or switch active
330gordon remotes use prod && gordon routes list
331gordon remotes use staging && gordon routes list
332```
333
334## Troubleshooting
335
336### "unauthorized" Error
337
338Token is missing, expired, or invalid.
339
340```bash
341# Check if token is set
342echo $GORDON_TOKEN
343
344# Verify token works
345gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
346```
347
348### "connection refused" Error
349
350Remote Gordon isn't running or URL is wrong.
351
352```bash
353# Verify URL is correct
354curl https://gordon.mydomain.com/health
355
356# Check if admin API is enabled on remote
357# The remote gordon.toml needs:
358# [admin]
359# enabled = true
360```
361
362### Remote Not Found
363
364The specified remote doesn't exist in `remotes.toml`.
365
366```bash
367# List available remotes
368gordon remotes list
369
370# Add the remote
371gordon remotes add myremote https://gordon.mydomain.com
372```
373
374### Active Remote Cleared
375
376After removing the active remote, you need to set a new active:
377
378```bash
379gordon remotes use prod
380```
381
382Or use explicit flags:
383
384```bash
385gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
386```
387
388## Related
389
390- [CLI Commands](/docs/cli/commands.md)
391- [Authentication](/docs/config/registry-auth.md)
392- [Admin API](/docs/config/admin.md)

remote-cli.md RawHistoryFolder