Authentication Commands
Manage Gordon server authentication tokens.
gordon auth
Subcommands
| Subcommand |
Description |
login |
Store a token for a remote Gordon server |
show-token |
Print the stored token for a remote |
logout |
Remove stored token for a remote |
status |
Check authentication session status |
token generate |
Generate a new JWT token |
token list |
List all stored tokens |
token revoke |
Revoke a token by ID (use --all to revoke all tokens) |
internal |
Show internal registry credentials |
gordon auth login
Store a pre-generated token for a remote Gordon server.
gordon auth login --token <token> [options]
Options
| Option |
Description |
-t, --token |
Required. Authentication token to store |
Use the global --remote, -r flag to target a specific remote. See CLI Overview.
Description
Stores a token for use with a remote Gordon server. The --token flag is required — generate a token on the server with gordon auth token generate.
When pass is available, the token is stored encrypted at gordon/remotes/<name>/token and plaintext fields are cleared from remotes.toml. When pass is unavailable, the token is stored in plaintext with a warning.
The token is verified against /admin/status on a best-effort basis.
Examples
gordon auth login --token <token>
gordon auth login --remote prod --token <token>
Output
When pass is available:
Token stored in pass for remote 'prod'
When pass is not available:
Warning: 'pass' not available. Storing token in plaintext config. Consider installing pass (https://www.passwordstore.org/) for secure token storage.
Token stored for remote 'prod'
gordon auth show-token
Print the stored token for a remote.
gordon auth show-token [--remote <name>]
Output is the raw token string, suitable for piping. Returns an error if no token is stored.
gordon auth show-token
gordon auth show-token --remote prod
gordon auth show-token | pbcopy # copy to clipboard
gordon auth logout
Remove the stored token for a remote.
gordon auth logout [--remote <name>]
Use the global --remote, -r flag to target a specific remote. See CLI Overview.
Deletes the token from pass and clears token fields in remotes.toml.
gordon auth token generate
Generate a new JWT authentication token for registry access.
gordon auth token generate --subject <name> [options]
Options
| Option |
Default |
Description |
--subject |
(required) |
Username/subject for the token |
--scopes |
push,pull |
Comma-separated scopes |
--expiry |
30d |
Duration until expiry (0 = never) |
-c, --config |
Auto |
Path to config file |
Supports human-friendly duration units:
| Unit |
Description |
Example |
d |
Days (24 hours) |
30d |
w |
Weeks (7 days) |
2w |
M |
Months (30 days) |
6M |
y |
Years (365 days) |
1y |
Compound durations are also supported: 1y6M, 2w3d, 1d12h
Standard Go durations also work: 24h, 30m, 1h30m
Scopes
Registry scopes: push, pull, push,pull
Admin scopes: admin:*:*, admin:routes:read, admin:routes:write, admin:config:read, admin:config:write, admin:status:read, admin:logs:read, admin:volumes:read, admin:volumes:write, admin:secrets:read, admin:secrets:write
Combine scopes with commas:
gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
Examples
# CI token that never expires
gordon auth token generate --subject github-actions --expiry 0
# Read-only token for 30 days
gordon auth token generate --subject reader --scopes pull --expiry 30d
# Push-only token for 1 year
gordon auth token generate --subject builder --scopes push --expiry 1y
# Temporary token (24 hours)
gordon auth token generate --subject temp --expiry 24h
# Full admin access token
gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 6M
# Read-only admin token
gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
Output
Token generated successfully!
Subject: github-actions
Scopes: push, pull
Expiry: never
Token (use as password with docker login):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Usage: docker login -u github-actions -p <token> <registry>
gordon auth token list
List all stored authentication tokens.
gordon auth token list [options]
Output
ID Subject Expires Revoked
------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
gordon auth token revoke
Revoke a token by its ID.
gordon auth token revoke <token-id> [options]
gordon auth token revoke --all # Revoke all tokens
Example
gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
Output
Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
gordon auth internal
Display the auto-generated internal registry credentials.
gordon auth internal
Gordon generates temporary credentials for loopback-only communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
When registry auth is enabled, Gordon also generates a separate service token for its own registry-domain pulls. That token is not exposed via the CLI.
Output
Internal Registry Credentials
==============================
Username: gordon-internal
Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Usage:
docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Notes
- Credentials are regenerated each time Gordon starts
- Only available while Gordon is running
- Used for manual
docker pull from the local registry during debugging
- Separate from the service token used by Gordon core for registry-domain pulls
Use Cases
- Debugging image pull failures
- Manual recovery after deployment issues
- Inspecting images in the local registry
Token Scopes
| Scope |
Permission |
push |
Push images to registry |
pull |
Pull images from registry |
push,pull |
Both push and pull (default) |
admin:*:* |
Full admin access |
admin:routes:read |
Read-only routes access |
admin:routes:write |
Routes write access |
admin:config:read |
Read-only config access |
admin:config:write |
Config write access |
admin:status:read |
Read-only status/health |
admin:logs:read |
Read-only logs access |
admin:secrets:read |
List secret keys |
admin:secrets:write |
Set/delete secrets |
| Format |
Duration |
0 |
Never expires |
24h |
24 hours |
720h |
30 days |
8760h |
1 year |
Workflow Examples
CI/CD Setup
# Generate token for CI
gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
# Save token as CI secret
# GitHub: Settings > Secrets > New repository secret
# GitLab: Settings > CI/CD > Variables
Docker Login
# Using generated token
docker login -u ci-bot -p <token> registry.mydomain.com
# In CI/CD
echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
Token Rotation
# Generate new token
gordon auth token generate --subject ci-bot --expiry 0
# Update CI secrets with new token
# Revoke old token
gordon auth token revoke <old-token-id>
Token-only Setup
# Create token secret
pass insert gordon/auth/token_secret
# Enter a random 32+ character string
# Configure gordon.toml
[auth]
enabled = true
secrets_backend = "pass"
token_secret = "gordon/auth/token_secret"
# Generate a deploy token
gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
source
1# Authentication Commands
2
3Manage Gordon server authentication tokens.
4
5## gordon auth
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `login` | Store a token for a remote Gordon server |
12| `show-token` | Print the stored token for a remote |
13| `logout` | Remove stored token for a remote |
14| `status` | Check authentication session status |
15| `token generate` | Generate a new JWT token |
16| `token list` | List all stored tokens |
17| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
18| `internal` | Show internal registry credentials |
19
20---
21
22## gordon auth login
23
24Store a pre-generated token for a remote Gordon server.
25
26```bash
27gordon auth login --token <token> [options]
28```
29
30### Options
31
32| Option | Description |
33|--------|-------------|
34| `-t, --token` | **Required.** Authentication token to store |
35
36Use the global `--remote, -r` flag to target a specific remote. See [CLI Overview](./index.md).
37
38### Description
39
40Stores a token for use with a remote Gordon server. The `--token` flag is required — generate a token on the server with `gordon auth token generate`.
41
42When [pass](https://www.passwordstore.org/) is available, the token is stored encrypted at `gordon/remotes/<name>/token` and plaintext fields are cleared from `remotes.toml`. When `pass` is unavailable, the token is stored in plaintext with a warning.
43
44The token is verified against `/admin/status` on a best-effort basis.
45
46### Examples
47
48```bash
49gordon auth login --token <token>
50gordon auth login --remote prod --token <token>
51```
52
53### Output
54
55When `pass` is available:
56
57```text
58Token stored in pass for remote 'prod'
59```
60
61When `pass` is not available:
62
63```text
64Warning: 'pass' not available. Storing token in plaintext config. Consider installing pass (https://www.passwordstore.org/) for secure token storage.
65Token stored for remote 'prod'
66```
67
68---
69
70## gordon auth show-token
71
72Print the stored token for a remote.
73
74```bash
75gordon auth show-token [--remote <name>]
76```
77
78Output is the raw token string, suitable for piping. Returns an error if no token is stored.
79
80```bash
81gordon auth show-token
82gordon auth show-token --remote prod
83gordon auth show-token | pbcopy # copy to clipboard
84```
85
86---
87
88## gordon auth logout
89
90Remove the stored token for a remote.
91
92```bash
93gordon auth logout [--remote <name>]
94```
95
96Use the global `--remote, -r` flag to target a specific remote. See [CLI Overview](./index.md).
97
98Deletes the token from pass and clears token fields in `remotes.toml`.
99
100---
101
102## gordon auth token generate
103
104Generate a new JWT authentication token for registry access.
105
106```bash
107gordon auth token generate --subject <name> [options]
108```
109
110### Options
111
112| Option | Default | Description |
113|--------|---------|-------------|
114| `--subject` | (required) | Username/subject for the token |
115| `--scopes` | `push,pull` | Comma-separated scopes |
116| `--expiry` | `30d` | Duration until expiry (0 = never) |
117| `-c, --config` | Auto | Path to config file |
118
119### Duration Format
120
121Supports human-friendly duration units:
122
123| Unit | Description | Example |
124|------|-------------|---------|
125| `d` | Days (24 hours) | `30d` |
126| `w` | Weeks (7 days) | `2w` |
127| `M` | Months (30 days) | `6M` |
128| `y` | Years (365 days) | `1y` |
129
130Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
131
132Standard Go durations also work: `24h`, `30m`, `1h30m`
133
134### Scopes
135
136Registry scopes: `push`, `pull`, `push,pull`
137
138Admin scopes: `admin:*:*`, `admin:routes:read`, `admin:routes:write`, `admin:config:read`, `admin:config:write`, `admin:status:read`, `admin:logs:read`, `admin:volumes:read`, `admin:volumes:write`, `admin:secrets:read`, `admin:secrets:write`
139
140Combine scopes with commas:
141
142```bash
143gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
144```
145
146### Examples
147
148```bash
149# CI token that never expires
150gordon auth token generate --subject github-actions --expiry 0
151
152# Read-only token for 30 days
153gordon auth token generate --subject reader --scopes pull --expiry 30d
154
155# Push-only token for 1 year
156gordon auth token generate --subject builder --scopes push --expiry 1y
157
158# Temporary token (24 hours)
159gordon auth token generate --subject temp --expiry 24h
160
161# Full admin access token
162gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 6M
163
164# Read-only admin token
165gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
166```
167
168### Output
169
170```
171Token generated successfully!
172Subject: github-actions
173Scopes: push, pull
174Expiry: never
175
176Token (use as password with docker login):
177eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
178
179Usage: docker login -u github-actions -p <token> <registry>
180```
181
182---
183
184## gordon auth token list
185
186List all stored authentication tokens.
187
188```bash
189gordon auth token list [options]
190```
191
192### Output
193
194```
195ID Subject Expires Revoked
196------------------------------------------------------------------------------------------
197a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
198b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
199c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
200```
201
202---
203
204## gordon auth token revoke
205
206Revoke a token by its ID.
207
208```bash
209gordon auth token revoke <token-id> [options]
210gordon auth token revoke --all # Revoke all tokens
211```
212
213### Example
214
215```bash
216gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
217```
218
219### Output
220
221```
222Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
223```
224
225---
226
227## gordon auth internal
228
229Display the auto-generated internal registry credentials.
230
231```bash
232gordon auth internal
233```
234
235Gordon generates temporary credentials for loopback-only communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
236
237When registry auth is enabled, Gordon also generates a separate service token for its own registry-domain pulls. That token is not exposed via the CLI.
238
239### Output
240
241```
242Internal Registry Credentials
243==============================
244Username: gordon-internal
245Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
246
247Usage:
248 docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
249```
250
251### Notes
252
253- Credentials are regenerated each time Gordon starts
254- Only available while Gordon is running
255- Used for manual `docker pull` from the local registry during debugging
256- Separate from the service token used by Gordon core for registry-domain pulls
257
258### Use Cases
259
260- Debugging image pull failures
261- Manual recovery after deployment issues
262- Inspecting images in the local registry
263
264---
265
266## Token Scopes
267
268| Scope | Permission |
269|-------|------------|
270| `push` | Push images to registry |
271| `pull` | Pull images from registry |
272| `push,pull` | Both push and pull (default) |
273| `admin:*:*` | Full admin access |
274| `admin:routes:read` | Read-only routes access |
275| `admin:routes:write` | Routes write access |
276| `admin:config:read` | Read-only config access |
277| `admin:config:write` | Config write access |
278| `admin:status:read` | Read-only status/health |
279| `admin:logs:read` | Read-only logs access |
280| `admin:secrets:read` | List secret keys |
281| `admin:secrets:write` | Set/delete secrets |
282
283## Token Expiry Formats
284
285| Format | Duration |
286|--------|----------|
287| `0` | Never expires |
288| `24h` | 24 hours |
289| `720h` | 30 days |
290| `8760h` | 1 year |
291
292---
293
294## Workflow Examples
295
296### CI/CD Setup
297
298```bash
299# Generate token for CI
300gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
301
302# Save token as CI secret
303# GitHub: Settings > Secrets > New repository secret
304# GitLab: Settings > CI/CD > Variables
305```
306
307### Docker Login
308
309```bash
310# Using generated token
311docker login -u ci-bot -p <token> registry.mydomain.com
312
313# In CI/CD
314echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
315```
316
317### Token Rotation
318
319```bash
320# Generate new token
321gordon auth token generate --subject ci-bot --expiry 0
322
323# Update CI secrets with new token
324
325# Revoke old token
326gordon auth token revoke <old-token-id>
327```
328
329### Token-only Setup
330
331```bash
332# Create token secret
333pass insert gordon/auth/token_secret
334# Enter a random 32+ character string
335
336# Configure gordon.toml
337[auth]
338enabled = true
339secrets_backend = "pass"
340token_secret = "gordon/auth/token_secret"
341
342# Generate a deploy token
343gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
344```
345
346## Related
347
348- [CLI Overview](./index.md)
349- [Authentication Configuration](../config/auth.md)