docs: update auth CLI docs for token exchange and new commands

commit: 7c8965b70a51a5da55cb738181d098be415dca34
author: brice · 7mo ago · 2026-03-22 20:13 UTC
parent: 16515bf
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +50 -9

M docs/cli/auth.md +45 -8


@@ -8,7 +8,10 @@ Manage Gordon server authentication tokens.
8	8
9	9		\| Subcommand \| Description \|
10	10		\|------------\|-------------\|
11		-	\| `login` \| Authenticate with a remote Gordon server \|
	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 \|
12	15		\| `token generate` \| Generate a new JWT token \|
13	16		\| `token list` \| List all stored tokens \|
14	17		\| `token revoke` \| Revoke a token by ID (use `--all` to revoke all tokens) \|

@@ -18,32 +21,31 @@ Manage Gordon server authentication tokens.
18	21
19	22		## gordon auth login
20	23
21		-	Authenticate with a remote Gordon server using a pre-generated token.
	24	+	Store a pre-generated token for a remote Gordon server.
22	25
23	26		```bash
24		-	gordon auth login [options]
	27	+	gordon auth login --token <token> [options]
25	28		```
26	29
27	30		### Options
28	31
29	32		\| Option \| Description \|
30	33		\|--------\|-------------\|
	34	+	\| `-t, --token` \| Required. Authentication token to store \|
31	35		\| `-r, --remote` \| Remote to authenticate with (defaults to active remote) \|
32		-	\| `-t, --token` \| Authentication token to store for the remote \|
33	36
34	37		### Description
35	38
36		-	This command stores a pre-generated token for use with a remote Gordon server. When [pass](https://www.passwordstore.org/) is available, the token is stored encrypted at `gordon/remotes/<name>/token` and any plaintext token fields are cleared from `remotes.toml`. When `pass` is unavailable, the token is stored in plaintext in `remotes.toml` with a warning.
	39	+	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`.
	40	+
	41	+	When [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.
37	42
38	43		The token is verified against `/admin/status` on a best-effort basis.
39	44
40	45		### Examples
41	46
42	47		```bash
43		-	# Store a token for the active remote
44	48		gordon auth login --token <token>
45		-
46		-	# Store a token for a specific remote
47	49		gordon auth login --remote prod --token <token>
48	50		```
49	51

@@ -64,6 +66,41 @@ Token stored for remote 'prod'
64	66
65	67		---
66	68
	69	+	## gordon auth show-token
	70	+
	71	+	Print the stored token for a remote.
	72	+
	73	+	```bash
	74	+	gordon auth show-token [--remote <name>]
	75	+	```
	76	+
	77	+	Output is the raw token string, suitable for piping. Returns an error if no token is stored.
	78	+
	79	+	```bash
	80	+	gordon auth show-token
	81	+	gordon auth show-token --remote prod
	82	+	gordon auth show-token \| pbcopy # copy to clipboard
	83	+	```
	84	+
	85	+	---
	86	+
	87	+	## gordon auth logout
	88	+
	89	+	Remove the stored token for a remote.
	90	+
	91	+	```bash
	92	+	gordon auth logout [--remote <name>] [--revoke]
	93	+	```
	94	+
	95	+	\| Option \| Description \|
	96	+	\|--------\|-------------\|
	97	+	\| `-r, --remote` \| Remote to log out from (defaults to active remote) \|
	98	+	\| `--revoke` \| Also revoke the token server-side (not yet implemented) \|
	99	+
	100	+	Deletes the token from pass and clears token fields in `remotes.toml`.
	101	+
	102	+	---
	103	+
67	104		## gordon auth token generate
68	105
69	106		Generate a new JWT authentication token for registry access.

 | Subcommand | Description |
 |------------|-------------|
-| `login` | Authenticate with a remote Gordon server |
+| `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) |
 ## gordon auth login
-Authenticate with a remote Gordon server using a pre-generated token.
+Store a pre-generated token for a remote Gordon server.
 ```bash
-gordon auth login [options]
+gordon auth login --token <token> [options]
 ```
 ### Options
 | Option | Description |
 |--------|-------------|
+| `-t, --token` | **Required.** Authentication token to store |
 | `-r, --remote` | Remote to authenticate with (defaults to active remote) |
-| `-t, --token` | Authentication token to store for the remote |
 ### Description
-This command stores a pre-generated token for use with a remote Gordon server. When [pass](https://www.passwordstore.org/) is available, the token is stored encrypted at `gordon/remotes/<name>/token` and any plaintext token fields are cleared from `remotes.toml`. When `pass` is unavailable, the token is stored in plaintext in `remotes.toml` with a warning.
+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](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.
 The token is verified against `/admin/status` on a best-effort basis.
 ### Examples
 ```bash
-# Store a token for the active remote
 gordon auth login --token <token>
-# Store a token for a specific remote
 gordon auth login --remote prod --token <token>
 ```
 ---
+## gordon auth show-token
+Print the stored token for a remote.
+```bash
+gordon auth show-token [--remote <name>]
+```
+Output is the raw token string, suitable for piping. Returns an error if no token is stored.
+```bash
+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.
+```bash
+gordon auth logout [--remote <name>] [--revoke]
+```
+| Option | Description |
+|--------|-------------|
+| `-r, --remote` | Remote to log out from (defaults to active remote) |
+| `--revoke` | Also revoke the token server-side (not yet implemented) |
+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.

M docs/upgrading.md +5 -1


@@ -13,12 +13,16 @@ Gordon v2.30.0 removes password-based authentication entirely. Only token-based
13	13		- `auth.type = "password"` is no longer accepted
14	14		- `auth.password` and `auth.password_hash` config fields are removed
15	15		- The `gordon auth password hash` CLI command is removed
16		-	- The `gordon auth login` command no longer accepts `--username` or `--password` flags
	16	+	- The `gordon auth login` command now requires `--token` (no more interactive password prompt)
17	17		- The `/auth/password` endpoint now returns `410 Gone`
	18	+	- Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via `/auth/token`
18	19
19	20		New features:
20	21
21	22		- `auth.access_token_ttl` configures the lifetime of ephemeral access tokens issued by `/auth/token` (default: `"15m"`)
	23	+	- `gordon auth show-token` prints the stored token for a remote
	24	+	- `gordon auth logout` removes the stored token (with optional `--revoke`)
	25	+	- Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
22	26		- Admin scopes (`admin::`, `admin:routes:read`, etc.) allow fine-grained access control for remote CLI operations
23	27
24	28		Migration steps:

 - `auth.type = "password"` is no longer accepted
 - `auth.password` and `auth.password_hash` config fields are removed
 - The `gordon auth password hash` CLI command is removed
-- The `gordon auth login` command no longer accepts `--username` or `--password` flags
+- The `gordon auth login` command now requires `--token` (no more interactive password prompt)
 - The `/auth/password` endpoint now returns `410 Gone`
+- Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via `/auth/token`
 **New features:**
 - `auth.access_token_ttl` configures the lifetime of ephemeral access tokens issued by `/auth/token` (default: `"15m"`)
+- `gordon auth show-token` prints the stored token for a remote
+- `gordon auth logout` removes the stored token (with optional `--revoke`)
+- Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
 - Admin scopes (`admin:*:*`, `admin:routes:read`, etc.) allow fine-grained access control for remote CLI operations
 **Migration steps:**