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.
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| `--remote` | Remote Gordon URL |
43| `--token` | Authentication token for remote |
44
45### Examples
46
47```bash
48# Local
49gordon secrets list myapp.local
50
51# Remote (override)
52gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
53```
54
55### Output
56
57```
58Secret                    Value (masked)
59--------------------------------------------------------------------------------
60DATABASE_URL              postgres://...
61API_KEY                   ****
62JWT_SECRET                ****
63```
64
65---
66
67## gordon secrets set
68
69Set a secret value for a domain.
70
71```bash
72gordon secrets set <domain> <key> <value>
73gordon secrets set myapp.local DATABASE_URL "postgres://..."
74```
75
76### Arguments
77
78| Argument | Description |
79|----------|-------------|
80| `<domain>` | The domain name to set the secret for |
81| `<key>` | The secret key (environment variable name) |
82| `<value>` | The secret value |
83
84### Options
85
86| Option | Description |
87|--------|-------------|
88| `--remote` | Remote Gordon URL |
89| `--token` | Authentication token for remote |
90
91### Examples
92
93```bash
94# Local
95gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/db"
96gordon secrets set myapp.local API_KEY "your-api-key"
97
98# Remote (override)
99gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote https://gordon.mydomain.com --token $TOKEN
100```
101
102---
103
104## gordon secrets remove
105
106Remove a secret from a domain.
107
108```bash
109gordon secrets remove <domain> <key>
110```
111
112### Arguments
113
114| Argument | Description |
115|----------|-------------|
116| `<domain>` | The domain name |
117| `<key>` | The secret key to remove |
118
119### Options
120
121| Option | Description |
122|--------|-------------|
123| `--remote` | Remote Gordon URL |
124| `--token` | Authentication token for remote |
125
126### Examples
127
128```bash
129# Local
130gordon secrets remove myapp.local DATABASE_URL
131
132# Remote (override)
133gordon secrets remove myapp.local DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
134```
135
136---
137
138## Workflow Examples
139
140### Setting Up Application Secrets
141
142```bash
143# Database connection
144gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/mydb"
145
146# API keys
147gordon secrets set myapp.local STRIPE_KEY "sk_live_..."
148gordon secrets set myapp.local SENDGRID_KEY "SG..."
149
150# JWT secret
151gordon secrets set myapp.local JWT_SECRET "your-jwt-secret-here"
152
153# Verify
154gordon secrets list myapp.local
155```
156
157### CI/CD Secret Management
158
159```bash
160# In your CI/CD pipeline
161export GORDON_REMOTE=https://gordon.mydomain.com
162export GORDON_TOKEN=$GORDON_TOKEN
163
164# Update secrets before deploy
165gordon secrets set myapp.example.com DATABASE_URL "$DATABASE_URL"
166gordon secrets set myapp.example.com API_KEY "$API_KEY"
167
168# Deploy
169gordon routes deploy myapp.example.com
170```
171
172### Rotating Secrets
173
174```bash
175# Generate new secret
176NEW_JWT_SECRET=$(openssl rand -base64 32)
177
178# Update the secret
179gordon secrets set myapp.local JWT_SECRET "$NEW_JWT_SECRET"
180
181# Redeploy to pick up new secret
182gordon routes deploy myapp.local
183```
184
185## Related
186
187- [CLI Overview](./index.md)
188- [Secrets Configuration](../config/secrets.md)
189- [Environment Variables](../config/env.md)