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
16---
17
18## gordon remotes list
19
20List all saved remotes.
21
22```bash
23gordon remotes list
24```
25
26### Output
27
28```
29Saved Remotes
30
31Name            URL                                    Token           Status
32-------------------------------------------------------------------------------
33prod            https://gordon.mydomain.com            $PROD_TOKEN     active
34staging         https://staging.mydomain.com           set
35dev             https://dev.mydomain.com               none
36```
37
38---
39
40## gordon remotes add
41
42Add a new remote.
43
44```bash
45gordon remotes add <name> <url> [options]
46```
47
48### Arguments
49
50| Argument | Description |
51|----------|-------------|
52| `<name>` | Name for the remote (e.g., `prod`, `staging`) |
53| `<url>` | Gordon URL (the `gordon_domain` from remote config) |
54
55### Options
56
57| Option | Description |
58|--------|-------------|
59| `--token` | Store token directly in config |
60| `--token-env` | Store environment variable name (token resolved at runtime) |
61
62### Examples
63
64```bash
65# Basic (no token)
66gordon remotes add prod https://gordon.mydomain.com
67
68# With direct token
69gordon remotes add prod https://gordon.mydomain.com --token eyJ...
70
71# With environment variable reference (recommended)
72gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
73```
74
75### Token Security
76
77**Option 1: Environment Variable Reference (Recommended)**
78
79```bash
80gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
81```
82
83The `remotes.toml` stores only the variable name:
84
85```toml
86[remotes.prod]
87url = "https://gordon.mydomain.com"
88token_env = "PROD_TOKEN"
89```
90
91At runtime, Gordon reads `$PROD_TOKEN` from the environment.
92
93**Option 2: Direct Token Storage**
94
95```bash
96gordon remotes add prod https://gordon.mydomain.com --token eyJ...
97```
98
99The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
100
101```bash
102chmod 600 ~/.config/gordon/remotes.toml
103```
104
105---
106
107## gordon remotes remove
108
109Remove a saved remote.
110
111```bash
112gordon remotes remove <name>
113gordon remotes remove <name> --force  # Skip confirmation
114```
115
116### Arguments
117
118| Argument | Description |
119|----------|-------------|
120| `<name>` | Name of the remote to remove |
121
122### Options
123
124| Option | Description |
125|--------|-------------|
126| `--force` | Skip confirmation prompt |
127
128### Example
129
130```bash
131gordon remotes remove staging
132```
133
134---
135
136## gordon remotes use
137
138Set the active remote.
139
140```bash
141gordon remotes use <name>
142```
143
144### Arguments
145
146| Argument | Description |
147|----------|-------------|
148| `<name>` | Name of the remote to set as active |
149
150### Description
151
152When a remote is active, it's used automatically for all remote-capable commands without needing to specify `--remote` and `--token`:
153
154```bash
155gordon remotes use prod
156gordon routes list              # Uses prod remote automatically
157gordon secrets list app.com     # Uses prod remote automatically
158```
159
160### Example
161
162```bash
163gordon remotes use prod
164```
165
166---
167
168## Configuration File
169
170Remotes are stored in `~/.config/gordon/remotes.toml`:
171
172```toml
173active = "prod"
174
175[remotes.prod]
176url = "https://gordon.mydomain.com"
177token_env = "PROD_TOKEN"
178
179[remotes.staging]
180url = "https://staging.mydomain.com"
181token = "eyJ..."
182```
183
184## Resolution Precedence
185
186When multiple sources specify remote or token, the CLI uses this priority:
187
188**Remote URL:**
1891. `--remote` flag
1902. `GORDON_REMOTE` environment variable
1913. Active remote from `remotes.toml`
192
193**Token:**
1941. `--token` flag
1952. `GORDON_TOKEN` environment variable
1963. Token from active remote in `remotes.toml`
197
198This allows overriding specific values while keeping defaults:
199
200```bash
201# Active remote is prod, but use different token
202gordon routes list --token $TEMPORARY_TOKEN
203```
204
205---
206
207## Workflow Examples
208
209### Multi-Environment Setup
210
211```bash
212# Add all environments
213gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
214gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
215gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
216
217# Work with prod
218gordon remotes use prod
219gordon routes list
220gordon secrets list myapp.example.com
221
222# Switch to staging
223gordon remotes use staging
224gordon routes list
225```
226
227### CI/CD Pipeline
228
229```yaml
230# GitHub Actions example
231env:
232  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
233  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
234
235steps:
236  - name: Deploy to Gordon
237    run: |
238      gordon routes deploy myapp.example.com
239```
240
241### Compare Environments
242
243```bash
244# Compare routes across environments
245gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
246gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
247
248# Or switch between active remotes
249gordon remotes use prod && gordon routes list
250gordon remotes use staging && gordon routes list
251```
252
253## Related
254
255- [CLI Overview](./index.md)
256- [Remote CLI Guide](/wiki/guides/remote-cli.md)