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`: secrets live in domain `.env` files and can reference SOPS-encrypted values
11- `unsafe`: secrets are stored in plain-text domain `.env` files
12
13## gordon secrets
14
15### Subcommands
16
17| Subcommand | Description |
18|------------|-------------|
19| `list` | List all secrets for a domain |
20| `set` | Set a secret value |
21| `remove` | Remove a secret |
22
23---
24
25## gordon secrets list
26
27List all secrets for a specific domain. When attachment secrets are present, they are displayed in a tree view below the domain secrets.
28
29```bash
30gordon secrets list <domain>
31```
32
33### Arguments
34
35| Argument | Description |
36|----------|-------------|
37| `<domain>` | The domain name to list secrets for |
38
39### Options
40
41| Option | Description |
42|--------|-------------|
43| `--json` | Output secrets as JSON |
44| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
45| `--token` | Authentication token for remote |
46
47### Examples
48
49```bash
50# Local
51gordon secrets list myapp.example.com
52
53# Remote (override)
54gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
55```
56
57### Output
58
59```
60Secrets for app.mydomain.com
61
62Key                       Value
63DATABASE_URL              ****
64API_KEY                   ****
65├─ [postgres]
66│  ├─ POSTGRES_USER       ****
67│  └─ POSTGRES_PASSWORD   ****
68└─ [redis]
69   └─ REDIS_PASSWORD      ****
70```
71
72### JSON Output
73
74```bash
75gordon secrets list app.mydomain.com --json
76```
77
78```json
79{
80  "domain": "app.mydomain.com",
81  "secrets": {
82    "DATABASE_URL": "****",
83    "API_KEY": "****"
84  },
85  "attachments": {
86    "postgres": {
87      "POSTGRES_USER": "****",
88      "POSTGRES_PASSWORD": "****"
89    },
90    "redis": {
91      "REDIS_PASSWORD": "****"
92    }
93  }
94}
95```
96
97---
98
99## gordon secrets set
100
101Set a secret value for a domain.
102
103```bash
104gordon secrets set <domain> <KEY=value>...
105gordon secrets set myapp.example.com DATABASE_URL="postgres://..."
106```
107
108### Arguments
109
110| Argument | Description |
111|----------|-------------|
112| `<domain>` | The domain name to set the secret for |
113| `<KEY=value>...` | One or more secret key/value pairs |
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.example.com DATABASE_URL="postgres://user:pass@postgres:5432/db"
128gordon secrets set myapp.example.com API_KEY="your-api-key"
129
130# Remote (override)
131gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL" --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| `--force` | Remove without confirmation |
164| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
165| `--token` | Authentication token for remote |
166
167### Examples
168
169```bash
170# Local
171gordon secrets remove myapp.example.com DATABASE_URL
172
173# Remote (override)
174gordon secrets remove myapp.example.com DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
175
176# Remove attachment secret
177gordon secrets remove app.mydomain.com --attachment postgres POSTGRES_PASSWORD
178```
179
180---
181
182## Workflow Examples
183
184### Setting Up Application Secrets
185
186```bash
187# Database connection
188gordon secrets set myapp.example.com DATABASE_URL="postgres://user:pass@postgres:5432/mydb"
189
190# API keys
191gordon secrets set myapp.example.com STRIPE_KEY="sk_live_..."
192gordon secrets set myapp.example.com SENDGRID_KEY="SG..."
193
194# JWT secret
195gordon secrets set myapp.example.com JWT_SECRET="your-jwt-secret-here"
196
197# Verify
198gordon secrets list myapp.example.com
199```
200
201### CI/CD Secret Management
202
203```bash
204# In your CI/CD pipeline
205export GORDON_REMOTE=https://gordon.mydomain.com
206export GORDON_TOKEN=$GORDON_TOKEN
207
208# Update secrets before deploy
209gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL"
210gordon secrets set myapp.example.com API_KEY="$API_KEY"
211
212# Deploy
213gordon deploy myapp.example.com
214```
215
216### Rotating Secrets
217
218```bash
219# Generate new secret
220NEW_JWT_SECRET=$(openssl rand -base64 32)
221
222# Update the secret
223gordon secrets set myapp.example.com JWT_SECRET="$NEW_JWT_SECRET"
224
225# Redeploy to pick up new secret
226gordon deploy myapp.example.com
227```
228
229### Attachment Secrets
230
231```bash
232# Configure database credentials
233gordon secrets set app.mydomain.com -a postgres POSTGRES_USER=admin POSTGRES_PASSWORD=secret
234
235# Configure cache credentials
236gordon secrets set app.mydomain.com -a redis REDIS_PASSWORD=cache-secret
237
238# Verify
239gordon secrets list app.mydomain.com
240
241# Redeploy to pick up new secrets
242gordon deploy app.mydomain.com
243```
244
245## Related
246
247- [CLI Overview](./index.md)
248- [Secrets Configuration](../config/secrets.md)
249- [Environment Variables](../config/env.md)