1# Secrets Commands
2
3Manage secrets on local or remote Gordon instances.
4
5Remote targeting uses client config or an active remote by default.
6When you provide a concrete domain and no remote is selected, Gordon can also
7auto-infer a saved remote when exactly one match is found.
8Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
9
10Storage depends on the secrets backend:
11- `pass`: secrets are stored in pass under `gordon/env/<domain>/<KEY>`
12- `sops`: secrets live in domain `.env` files and can reference SOPS-encrypted values
13- `unsafe`: secrets are stored in plain-text domain `.env` files
14
15## gordon secrets
16
17### Subcommands
18
19| Subcommand | Description |
20|------------|-------------|
21| `list` | List all secrets for a domain |
22| `set` | Set a secret value |
23| `remove` | Remove a secret |
24
25---
26
27## gordon secrets list
28
29List all secrets for a specific domain. When attachment secrets are present, they are displayed in a tree view below the domain secrets.
30
31```bash
32gordon secrets list <domain>
33```
34
35### Arguments
36
37| Argument | Description |
38|----------|-------------|
39| `<domain>` | The domain name to list secrets for |
40
41### Options
42
43| Option | Description |
44|--------|-------------|
45| `--json` | Output secrets as JSON |
46| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
47| `--token` | Authentication token for remote |
48
49### Examples
50
51```bash
52# Local
53gordon secrets list myapp.example.com
54
55# Remote (override)
56gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
57```
58
59### Output
60
61```
62Secrets for app.mydomain.com
63
64Key                       Value
65DATABASE_URL              ****
66API_KEY                   ****
67├─ [postgres]
68│  ├─ POSTGRES_USER       ****
69│  └─ POSTGRES_PASSWORD   ****
70└─ [redis]
71   └─ REDIS_PASSWORD      ****
72```
73
74### JSON Output
75
76```bash
77gordon secrets list app.mydomain.com --json
78```
79
80```json
81{
82  "domain": "app.mydomain.com",
83  "secrets": {
84    "DATABASE_URL": "****",
85    "API_KEY": "****"
86  },
87  "attachments": {
88    "postgres": {
89      "POSTGRES_USER": "****",
90      "POSTGRES_PASSWORD": "****"
91    },
92    "redis": {
93      "REDIS_PASSWORD": "****"
94    }
95  }
96}
97```
98
99---
100
101## gordon secrets set
102
103Set a secret value for a domain.
104
105```bash
106gordon secrets set <domain> <KEY=value>...
107gordon secrets set myapp.example.com DATABASE_URL="postgres://..."
108```
109
110### Arguments
111
112| Argument | Description |
113|----------|-------------|
114| `<domain>` | The domain name to set the secret for |
115| `<KEY=value>...` | One or more secret key/value pairs |
116
117### Options
118
119| Option | Description |
120|--------|-------------|
121| `--attachment` / `-a` | Target an attachment service (e.g., postgres, redis) |
122| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
123| `--token` | Authentication token for remote |
124
125### Examples
126
127```bash
128# Local
129gordon secrets set myapp.example.com DATABASE_URL="postgres://user:pass@postgres:5432/db"
130gordon secrets set myapp.example.com API_KEY="your-api-key"
131
132# Remote (override)
133gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL" --remote https://gordon.mydomain.com --token $TOKEN
134
135# Set attachment secrets
136gordon secrets set app.mydomain.com --attachment postgres POSTGRES_PASSWORD=secret
137gordon secrets set app.mydomain.com -a redis REDIS_PASSWORD=mysecret
138
139# Multiple secrets at once
140gordon secrets set app.mydomain.com -a postgres POSTGRES_USER=admin POSTGRES_PASSWORD=secret
141```
142
143---
144
145## gordon secrets remove
146
147Remove a secret from a domain.
148
149```bash
150gordon secrets remove <domain> <key>
151```
152
153### Arguments
154
155| Argument | Description |
156|----------|-------------|
157| `<domain>` | The domain name |
158| `<key>` | The secret key to remove |
159
160### Options
161
162| Option | Description |
163|--------|-------------|
164| `--attachment` / `-a` | Target an attachment service (e.g., postgres, redis) |
165| `--force` | Remove without confirmation |
166| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
167| `--token` | Authentication token for remote |
168
169### Examples
170
171```bash
172# Local
173gordon secrets remove myapp.example.com DATABASE_URL
174
175# Remote (override)
176gordon secrets remove myapp.example.com DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
177
178# Remove attachment secret
179gordon secrets remove app.mydomain.com --attachment postgres POSTGRES_PASSWORD
180```
181
182---
183
184## Workflow Examples
185
186### Setting Up Application Secrets
187
188```bash
189# Database connection
190gordon secrets set myapp.example.com DATABASE_URL="postgres://user:pass@postgres:5432/mydb"
191
192# API keys
193gordon secrets set myapp.example.com STRIPE_KEY="sk_live_..."
194gordon secrets set myapp.example.com SENDGRID_KEY="SG..."
195
196# JWT secret
197gordon secrets set myapp.example.com JWT_SECRET="your-jwt-secret-here"
198
199# Verify
200gordon secrets list myapp.example.com
201```
202
203### CI/CD Secret Management
204
205```bash
206# In your CI/CD pipeline
207export GORDON_REMOTE=https://gordon.mydomain.com
208export GORDON_TOKEN=$GORDON_TOKEN
209
210# Update secrets before deploy
211gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL"
212gordon secrets set myapp.example.com API_KEY="$API_KEY"
213
214# Deploy
215gordon deploy myapp.example.com
216```
217
218### Rotating Secrets
219
220```bash
221# Generate new secret
222NEW_JWT_SECRET=$(openssl rand -base64 32)
223
224# Update the secret
225gordon secrets set myapp.example.com JWT_SECRET="$NEW_JWT_SECRET"
226
227# Redeploy to pick up new secret
228gordon deploy myapp.example.com
229```
230
231### Attachment Secrets
232
233```bash
234# Configure database credentials
235gordon secrets set app.mydomain.com -a postgres POSTGRES_USER=admin POSTGRES_PASSWORD=secret
236
237# Configure cache credentials
238gordon secrets set app.mydomain.com -a redis REDIS_PASSWORD=cache-secret
239
240# Verify
241gordon secrets list app.mydomain.com
242
243# Redeploy to pick up new secrets
244gordon deploy app.mydomain.com
245```
246
247## Related
248
249- [CLI Overview](./index.md)
250- [Secrets Configuration](../config/secrets.md)
251- [Environment Variables](../config/env.md)