1# Secrets Commands
2
3Manage installation secrets on local or remote Gordon instances.
4
5Storage depends on the secrets backend:
6- `pass`: secrets are stored in pass under `gordon/env/<domain>/<KEY>`
7- `sops`: secrets live in domain `.env` files and can reference SOPS-encrypted values
8- `unsafe`: secrets are stored in plain-text domain `.env` files
9
10App secret VALUES stay in pass under
11`gordon/apps/<uuid>/<service>/<name>` and are managed with
12`gordon apps secrets`. The commands below manage installation secrets only.
13
14## gordon secrets
15
16### Subcommands
17
18| Subcommand | Description |
19|------------|-------------|
20| `list` | List all secret keys for a domain |
21| `set` | Set secrets for a domain from a file |
22| `remove` | Remove a secret |
23
24---
25
26## gordon secrets list
27
28List all secret key names for a specific domain. Only key names are shown, never values.
29
30```bash
31gordon secrets list <domain>
32```
33
34### Arguments
35
36| Argument | Description |
37|----------|-------------|
38| `<domain>` | The domain name to list secrets for |
39
40### Options
41
42| Option | Description |
43|--------|-------------|
44| `--json` | Output secrets as JSON |
45| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
46| `--token` | Authentication token for remote |
47
48### Examples
49
50```bash
51# Local
52gordon secrets list myapp.example.com
53
54# Remote (override)
55gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
56```
57
58### Output
59
60```
61Secrets for app.mydomain.com
62
63Key                       Value
64DATABASE_URL              (hidden)
65API_KEY                   (hidden)
66```
67
68### JSON Output
69
70```bash
71gordon secrets list app.mydomain.com --json
72```
73
74```json
75{
76  "domain": "app.mydomain.com",
77  "keys": ["API_KEY", "DATABASE_URL"]
78}
79```
80
81---
82
83## gordon secrets set
84
85Set secrets for a domain from a mode 0600 file containing one `KEY=value` pair per line.
86
87```bash
88gordon secrets set <domain> --from-file <path>
89```
90
91### Arguments
92
93| Argument | Description |
94|----------|-------------|
95| `<domain>` | The domain name to set secrets for |
96
97### Options
98
99| Option | Description |
100|--------|-------------|
101| `--from-file` | Read KEY=value lines from a mode 0600 file (required) |
102| `--json` | Output as JSON |
103| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
104| `--token` | Authentication token for remote |
105
106### Examples
107
108```bash
109# Local
110gordon secrets set myapp.example.com --from-file ./app.env
111
112# Remote (override)
113gordon secrets set myapp.example.com --from-file ./app.env --remote https://gordon.mydomain.com --token $TOKEN
114```
115
116---
117
118## gordon secrets remove
119
120Remove a secret from a domain.
121
122```bash
123gordon secrets remove <domain> <key>
124```
125
126### Arguments
127
128| Argument | Description |
129|----------|-------------|
130| `<domain>` | The domain name |
131| `<key>` | The secret key to remove |
132
133### Options
134
135| Option | Description |
136|--------|-------------|
137| `--force`, `-f` | Remove without confirmation |
138| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
139| `--token` | Authentication token for remote |
140
141### Examples
142
143```bash
144# Local
145gordon secrets remove myapp.example.com DATABASE_URL
146
147# Remote (override)
148gordon secrets remove myapp.example.com DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
149```
150
151---
152
153## Workflow Examples
154
155### Setting Up Application Secrets
156
157```bash
158# Write secrets to a protected file
159cat > app.env <<'EOF'
160DATABASE_URL=postgres://user:pass@postgres:5432/mydb
161API_KEY=your-api-key
162EOF
163chmod 600 app.env
164
165gordon secrets set myapp.example.com --from-file ./app.env
166
167# Verify
168gordon secrets list myapp.example.com
169```
170
171### CI/CD Secret Management
172
173```bash
174# In your CI/CD pipeline
175export GORDON_REMOTE=https://gordon.mydomain.com
176export GORDON_TOKEN=$GORDON_TOKEN
177
178# Update secrets
179gordon secrets set myapp.example.com --from-file ./app.env
180```
181
182### Rotating Secrets
183
184```bash
185# Generate new secret
186NEW_JWT_SECRET=$(openssl rand -base64 32)
187printf 'JWT_SECRET=%s\n' "$NEW_JWT_SECRET" > rotate.env
188chmod 600 rotate.env
189
190# Update the secret
191gordon secrets set myapp.example.com --from-file ./rotate.env
192```
193
194## Related
195
196- [CLI Overview](./index.md)
197- [Secrets Configuration](../config/secrets.md)
198- [Environment Variables](../config/env.md)
199- [Apps Commands](./apps.md)