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