auth.md Raw History Folder

Authentication Commands

Manage Gordon server authentication tokens and passwords.

gordon auth

Subcommands

Subcommand	Description
`login`	Authenticate with a remote Gordon server
`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)
`password hash`	Generate bcrypt password hash
`internal`	Show internal registry credentials

Authenticate with a remote Gordon server using password authentication or a pre-generated token.

gordon auth login [options]

Options

Option	Description
`-r, --remote`	Remote to authenticate with (defaults to active remote)
`-u, --username`	Username for authentication
`-p, --password`	Password for authentication
`-t, --token`	Authentication token to store for the remote

Description

This command prompts for your username and password, authenticates with the remote server's /auth/password endpoint, and stores the returned token in your remotes configuration.

If you provide --token, the token is stored directly and verified against /admin/status on a best-effort basis.

The token is a long-lived JWT (7 days) that's used for subsequent CLI operations against the remote.

Note: For token-only servers, you can pass --token here or use gordon remotes set-token.

Examples

# Login using active remote
gordon auth login

# Login to specific remote
gordon auth login --remote prod

# Pre-fill username
gordon auth login --username admin

# Store a pre-generated token
gordon auth login --token <token>

Output

Username: admin
Password: ********
Authenticating with prod...

✓ Authentication successful!
Token stored for remote 'prod'
Expires in: 604800 seconds

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

Duration Format

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

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

# Token for 6 months
gordon auth token generate --subject deploy --expiry 6M

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 password hash

Generate a bcrypt hash for password authentication.

gordon auth password hash

Interactively prompts for a password and outputs the bcrypt hash.

Output

Enter password: ********

Bcrypt hash (store in your secrets backend):
$2a$10$N9qo8uLOickgx2ZMRZoMye...

Then reference the path in your config:
  [auth]
  username = "deploy"
  password_hash = "gordon/auth/password_hash"
  token_secret = "gordon/auth/token_secret"

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)

Token Expiry Formats

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

# 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>

Password Setup

# Generate hash
gordon auth password hash
# Enter: mypassword

# Store in pass
pass insert gordon/auth/password_hash
# Paste: $2a$10$...

# Create token secret
pass insert gordon/auth/token_secret
# Enter a random 32+ character string

# Configure gordon.toml
[auth]
enabled = true
secrets_backend = "pass"
username = "deploy"
password_hash = "gordon/auth/password_hash"
token_secret = "gordon/auth/token_secret"

source

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

auth.md RawHistoryFolder

Authentication Commands

gordon auth

Subcommands

gordon auth login

Options

Description

Examples

Output

gordon auth token generate

Options

Duration Format

Examples

Output

gordon auth token list

Output

gordon auth token revoke

Example

Output

gordon auth password hash

Output

gordon auth internal

Output

Notes

Use Cases

Token Scopes

Token Expiry Formats

Workflow Examples

CI/CD Setup

Docker Login

Token Rotation

Password Setup

Related

auth.md Raw History Folder