docs: add bootstrap command and --json flag documentation

Document new bootstrap workflow for first deploys, update routes add
to reflect idempotent behavior, add --json flag examples to all list
command docs, and update getting-started guide.

Part of #98.

commit: 73b880ad2e6251e7d648e0c49ede7df12161498e
author: brice · 7mo ago · 2026-03-13 20:47 UTC
parent: 2b8d4f7
signature: unsigned

9 files · +236 -11

M docs/cli/attachments.md +28 -0


@@ -40,6 +40,7 @@ List all configured attachments.
40	40		```bash
41	41		# List all attachments
42	42		gordon attachments list
	43	+	gordon attachments list --json
43	44
44	45		# List attachments for a specific domain or group
45	46		gordon attachments list app.example.com

@@ -59,6 +60,33 @@ api.example.com postgres:18
59	60		backend (group) rabbitmq:3-management
60	61		```
61	62
	63	+	### JSON Output
	64	+
	65	+	```bash
	66	+	gordon attachments list --json
	67	+	```
	68	+
	69	+	```json
	70	+	[
	71	+	{
	72	+	"target": "app.example.com",
	73	+	"attachments": ["postgres:18", "redis:7-alpine"]
	74	+	},
	75	+	{
	76	+	"target": "backend",
	77	+	"attachments": ["rabbitmq:3-management"]
	78	+	}
	79	+	]
	80	+	```
	81	+
	82	+	### Options
	83	+
	84	+	\| Option \| Description \|
	85	+	\|--------\|-------------\|
	86	+	\| `--json` \| Output attachments as JSON \|
	87	+	\| `--remote` \| Remote Gordon URL \|
	88	+	\| `--token` \| Authentication token for remote \|
	89	+
62	90		---
63	91
64	92		## gordon attachments add


@@ -40,6 +40,7 @@ List all configured attachments.
40	```bash	40		```bash
41	# List all attachments	41		# List all attachments
42	gordon attachments list	42		gordon attachments list
		43	+	gordon attachments list --json
43		44
44	# List attachments for a specific domain or group	45		# List attachments for a specific domain or group
45	gordon attachments list app.example.com	46		gordon attachments list app.example.com

@@ -59,6 +60,33 @@ api.example.com postgres:18
59	backend (group) rabbitmq:3-management	60		backend (group) rabbitmq:3-management
60	```	61		```
61		62
		63	+	### JSON Output
		64	+
		65	+	```bash
		66	+	gordon attachments list --json
		67	+	```
		68	+
		69	+	```json
		70	+	[
		71	+	{
		72	+	"target": "app.example.com",
		73	+	"attachments": ["postgres:18", "redis:7-alpine"]
		74	+	},
		75	+	{
		76	+	"target": "backend",
		77	+	"attachments": ["rabbitmq:3-management"]
		78	+	}
		79	+	]
		80	+	```
		81	+
		82	+	### Options
		83	+
		84	+	\| Option \| Description \|
		85	+	\|--------\|-------------\|
		86	+	\| `--json` \| Output attachments as JSON \|
		87	+	\| `--remote` \| Remote Gordon URL \|
		88	+	\| `--token` \| Authentication token for remote \|
		89	+
62	---	90		---
63		91
64	## gordon attachments add	92		## gordon attachments add

M docs/cli/backup.md +21 -0


@@ -29,6 +29,7 @@ In normal usage, configure remotes once (`gordon remotes ...`) and run backup co
29	29		```bash
30	30		# List all backups
31	31		gordon backups list
	32	+	gordon backups list --json
32	33
33	34		# List backups for one domain
34	35		gordon backups list app.example.com

@@ -46,6 +47,26 @@ gordon backups detect app.example.com
46	47		gordon backups status
47	48		```
48	49
	50	+	## JSON Output
	51	+
	52	+	`gordon backups list` supports `--json` for machine-readable output.
	53	+
	54	+	```bash
	55	+	gordon backups list --json
	56	+	```
	57	+
	58	+	```json
	59	+	[
	60	+	{
	61	+	"domain": "app.example.com",
	62	+	"db": "postgres",
	63	+	"status": "completed",
	64	+	"started_at": "2026-03-13T09:45:00Z",
	65	+	"backup_id": "backup_20260313_094500"
	66	+	}
	67	+	]
	68	+	```
	69	+
49	70		## Output Columns
50	71
51	72		### list


@@ -29,6 +29,7 @@ In normal usage, configure remotes once (`gordon remotes ...`) and run backup co
29	```bash	29		```bash
30	# List all backups	30		# List all backups
31	gordon backups list	31		gordon backups list
		32	+	gordon backups list --json
32		33
33	# List backups for one domain	34		# List backups for one domain
34	gordon backups list app.example.com	35		gordon backups list app.example.com

@@ -46,6 +47,26 @@ gordon backups detect app.example.com
46	gordon backups status	47		gordon backups status
47	```	48		```
48		49
		50	+	## JSON Output
		51	+
		52	+	`gordon backups list` supports `--json` for machine-readable output.
		53	+
		54	+	```bash
		55	+	gordon backups list --json
		56	+	```
		57	+
		58	+	```json
		59	+	[
		60	+	{
		61	+	"domain": "app.example.com",
		62	+	"db": "postgres",
		63	+	"status": "completed",
		64	+	"started_at": "2026-03-13T09:45:00Z",
		65	+	"backup_id": "backup_20260313_094500"
		66	+	}
		67	+	]
		68	+	```
		69	+
49	## Output Columns	70		## Output Columns
50		71
51	### list	72		### list

A docs/cli/bootstrap.md +69 -0

@@ -0,0 +1,69 @@
	1	+	# Bootstrap Command
	2	+
	3	+	Create or update a route, then push and deploy an image in one command.
	4	+
	5	+	## gordon bootstrap
	6	+
	7	+	### Synopsis
	8	+
	9	+	```bash
	10	+	gordon bootstrap <domain> <image> [options]
	11	+	```
	12	+
	13	+	### Arguments
	14	+
	15	+	\| Argument \| Description \|
	16	+	\|----------\|-------------\|
	17	+	\| `<domain>` \| The route domain to create or update \|
	18	+	\| `<image>` \| The image to assign to the route \|
	19	+
	20	+	### Options
	21	+
	22	+	\| Option \| Description \|
	23	+	\|--------\|-------------\|
	24	+	\| `--attachment` \| Add an attachment to the route (repeatable) \|
	25	+	\| `--env` \| Set an environment variable for the route (repeatable, `KEY=VALUE`) \|
	26	+	\| `--remote` \| Remote Gordon URL \|
	27	+	\| `--token` \| Authentication token for remote \|
	28	+
	29	+	### Description
	30	+
	31	+	`gordon bootstrap` is the recommended first-deploy workflow.
	32	+
	33	+	- It creates the route when it does not exist.
	34	+	- It updates the route when it already exists.
	35	+	- It can attach services and set environment variables as part of the same command.
	36	+	- It then pushes and deploys the image for the target route.
	37	+
	38	+	Unlike `gordon push`, `gordon bootstrap` does not require the route to exist first.
	39	+
	40	+	### Examples
	41	+
	42	+	```bash
	43	+	# First deploy
	44	+	gordon bootstrap app.example.com myapp:latest
	45	+
	46	+	# First deploy with a database attachment and environment variable
	47	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
	48	+
	49	+	# Multiple attachments and environment variables
	50	+	gordon bootstrap app.example.com myapp:latest \
	51	+	--attachment postgres:18 \
	52	+	--attachment redis:7-alpine \
	53	+	--env APP_ENV=production \
	54	+	--env LOG_LEVEL=info
	55	+
	56	+	# Remote target
	57	+	gordon bootstrap app.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
	58	+	```
	59	+
	60	+	### Notes
	61	+
	62	+	- `gordon bootstrap` is idempotent for route configuration: rerunning it updates the route instead of failing.
	63	+	- Use `gordon push` for later image-only deploys when the route already exists.
	64	+
	65	+	## Related
	66	+
	67	+	- [CLI Overview](./index.md)
	68	+	- [Routes Commands](./routes.md)
	69	+	- [Push Command](./push.md)

@@ -0,0 +1,69 @@
	1	+	# Bootstrap Command
	2	+
	3	+	Create or update a route, then push and deploy an image in one command.
	4	+
	5	+	## gordon bootstrap
	6	+
	7	+	### Synopsis
	8	+
	9	+	```bash
	10	+	gordon bootstrap <domain> <image> [options]
	11	+	```
	12	+
	13	+	### Arguments
	14	+
	15	+	\| Argument \| Description \|
	16	+	\|----------\|-------------\|
	17	+	\| `<domain>` \| The route domain to create or update \|
	18	+	\| `<image>` \| The image to assign to the route \|
	19	+
	20	+	### Options
	21	+
	22	+	\| Option \| Description \|
	23	+	\|--------\|-------------\|
	24	+	\| `--attachment` \| Add an attachment to the route (repeatable) \|
	25	+	\| `--env` \| Set an environment variable for the route (repeatable, `KEY=VALUE`) \|
	26	+	\| `--remote` \| Remote Gordon URL \|
	27	+	\| `--token` \| Authentication token for remote \|
	28	+
	29	+	### Description
	30	+
	31	+	`gordon bootstrap` is the recommended first-deploy workflow.
	32	+
	33	+	- It creates the route when it does not exist.
	34	+	- It updates the route when it already exists.
	35	+	- It can attach services and set environment variables as part of the same command.
	36	+	- It then pushes and deploys the image for the target route.
	37	+
	38	+	Unlike `gordon push`, `gordon bootstrap` does not require the route to exist first.
	39	+
	40	+	### Examples
	41	+
	42	+	```bash
	43	+	# First deploy
	44	+	gordon bootstrap app.example.com myapp:latest
	45	+
	46	+	# First deploy with a database attachment and environment variable
	47	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
	48	+
	49	+	# Multiple attachments and environment variables
	50	+	gordon bootstrap app.example.com myapp:latest \
	51	+	--attachment postgres:18 \
	52	+	--attachment redis:7-alpine \
	53	+	--env APP_ENV=production \
	54	+	--env LOG_LEVEL=info
	55	+
	56	+	# Remote target
	57	+	gordon bootstrap app.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
	58	+	```
	59	+
	60	+	### Notes
	61	+
	62	+	- `gordon bootstrap` is idempotent for route configuration: rerunning it updates the route instead of failing.
	63	+	- Use `gordon push` for later image-only deploys when the route already exists.
	64	+
	65	+	## Related
	66	+
	67	+	- [CLI Overview](./index.md)
	68	+	- [Routes Commands](./routes.md)
	69	+	- [Push Command](./push.md)

M docs/cli/images.md +26 -0


@@ -19,11 +19,37 @@ Subcommands:
19	19
20	20		```bash
21	21		gordon images list
	22	+	gordon images list --json
22	23		```
23	24
24	25		Shows image rows with repository, tag, size, creation time, image id, and dangling status.
25	26		Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as `-`.
26	27
	28	+	Flags:
	29	+
	30	+	\| Flag \| Description \|
	31	+	\|------\|-------------\|
	32	+	\| `--json` \| Output images as JSON \|
	33	+
	34	+	### JSON Output
	35	+
	36	+	```bash
	37	+	gordon images list --json
	38	+	```
	39	+
	40	+	```json
	41	+	[
	42	+	{
	43	+	"repository": "myapp",
	44	+	"tag": "latest",
	45	+	"size": "148MB",
	46	+	"created_at": "2026-03-13T10:15:00Z",
	47	+	"image_id": "sha256:abc123def456",
	48	+	"dangling": false
	49	+	}
	50	+	]
	51	+	```
	52	+
27	53		## gordon images prune
28	54
29	55		```bash


@@ -19,11 +19,37 @@ Subcommands:
19		19
20	```bash	20		```bash
21	gordon images list	21		gordon images list
		22	+	gordon images list --json
22	```	23		```
23		24
24	Shows image rows with repository, tag, size, creation time, image id, and dangling status.	25		Shows image rows with repository, tag, size, creation time, image id, and dangling status.
25	Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as `-`.	26		Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as `-`.
26		27
		28	+	Flags:
		29	+
		30	+	\| Flag \| Description \|
		31	+	\|------\|-------------\|
		32	+	\| `--json` \| Output images as JSON \|
		33	+
		34	+	### JSON Output
		35	+
		36	+	```bash
		37	+	gordon images list --json
		38	+	```
		39	+
		40	+	```json
		41	+	[
		42	+	{
		43	+	"repository": "myapp",
		44	+	"tag": "latest",
		45	+	"size": "148MB",
		46	+	"created_at": "2026-03-13T10:15:00Z",
		47	+	"image_id": "sha256:abc123def456",
		48	+	"dangling": false
		49	+	}
		50	+	]
		51	+	```
		52	+
27	## gordon images prune	53		## gordon images prune
28		54
29	```bash	55		```bash

M docs/cli/index.md +6 -0


@@ -2,6 +2,8 @@
2	2
3	3		Gordon provides a command-line interface for server management, deployment, and authentication.
4	4
	5	+	Most `list` commands also support `--json` for machine-readable output.
	6	+
5	7		Commands are organized by where they run:
6	8
7	9		- Server Commands - Must run on the machine hosting Gordon

@@ -26,6 +28,7 @@ Management commands run locally through in-process services by default. Add `--r
26	28		\| `gordon secrets` \| Manage secrets \| [secrets](./secrets.md) \|
27	29		\| `gordon deploy` \| Manually deploy or redeploy a route \| [serve](./serve.md#gordon-deploy) \|
28	30		\| `gordon restart` \| Restart a running container \| [restart](./restart.md) \|
	31	+	\| `gordon bootstrap` \| Create or update a route, then push and deploy an image \| [bootstrap](./bootstrap.md) \|
29	32		\| `gordon push` \| Tag, push, and optionally deploy an image \| [push](./push.md) \|
30	33		\| `gordon rollback` \| Roll back to a previous image tag \| [rollback](./rollback.md) \|
31	34		\| `gordon reload` \| Reload configuration and sync containers \| [serve](./serve.md#gordon-reload) \|

@@ -58,6 +61,9 @@ gordon deploy myapp.example.com
58	61		# Restart a running container
59	62		gordon restart myapp.example.com
60	63
	64	+	# First deploy for a route
	65	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
	66	+
61	67		# Push an image and deploy
62	68		gordon push myapp.example.com --build
63	69


@@ -2,6 +2,8 @@
2		2
3	Gordon provides a command-line interface for server management, deployment, and authentication.	3		Gordon provides a command-line interface for server management, deployment, and authentication.
4		4
		5	+	Most `list` commands also support `--json` for machine-readable output.
		6	+
5	Commands are organized by where they run:	7		Commands are organized by where they run:
6		8
7	- Server Commands - Must run on the machine hosting Gordon	9		- Server Commands - Must run on the machine hosting Gordon

@@ -26,6 +28,7 @@ Management commands run locally through in-process services by default. Add `--r
26	\| `gordon secrets` \| Manage secrets \| [secrets](./secrets.md) \|	28		\| `gordon secrets` \| Manage secrets \| [secrets](./secrets.md) \|
27	\| `gordon deploy` \| Manually deploy or redeploy a route \| [serve](./serve.md#gordon-deploy) \|	29		\| `gordon deploy` \| Manually deploy or redeploy a route \| [serve](./serve.md#gordon-deploy) \|
28	\| `gordon restart` \| Restart a running container \| [restart](./restart.md) \|	30		\| `gordon restart` \| Restart a running container \| [restart](./restart.md) \|
		31	+	\| `gordon bootstrap` \| Create or update a route, then push and deploy an image \| [bootstrap](./bootstrap.md) \|
29	\| `gordon push` \| Tag, push, and optionally deploy an image \| [push](./push.md) \|	32		\| `gordon push` \| Tag, push, and optionally deploy an image \| [push](./push.md) \|
30	\| `gordon rollback` \| Roll back to a previous image tag \| [rollback](./rollback.md) \|	33		\| `gordon rollback` \| Roll back to a previous image tag \| [rollback](./rollback.md) \|
31	\| `gordon reload` \| Reload configuration and sync containers \| [serve](./serve.md#gordon-reload) \|	34		\| `gordon reload` \| Reload configuration and sync containers \| [serve](./serve.md#gordon-reload) \|

@@ -58,6 +61,9 @@ gordon deploy myapp.example.com
58	# Restart a running container	61		# Restart a running container
59	gordon restart myapp.example.com	62		gordon restart myapp.example.com
60		63
		64	+	# First deploy for a route
		65	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
		66	+
61	# Push an image and deploy	67		# Push an image and deploy
62	gordon push myapp.example.com --build	68		gordon push myapp.example.com --build
63		69

M docs/cli/push.md +2 -0


@@ -35,6 +35,7 @@ gordon push <domain> [options]
35	35		`gordon push` resolves the route image for `<domain>`, tags the image for the
36	36		Gordon registry, pushes it, and optionally deploys it.
37	37
	38	+	- For first deploys, prefer `gordon bootstrap`, which creates or updates the route and then pushes and deploys the image.
38	39		- The registry and repository are derived from the route image on the server.
39	40		- The version tag defaults to a CI tag ref (like `refs/tags/v1.2.3`) when available,
40	41		then falls back to `git describe --tags --dirty` (for example

@@ -66,6 +67,7 @@ gordon push myapp.example.com --build -f docker/app/Dockerfile
66	67		### Notes
67	68
68	69		- Remote mode required. See [CLI Overview](./index.md) for targeting options.
	70	+	- `gordon push` still requires the route to already exist so it can resolve the target image.
69	71		- `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux,
70	72		install the `docker-buildx-plugin` package.
71	73


@@ -35,6 +35,7 @@ gordon push <domain> [options]
35	`gordon push` resolves the route image for `<domain>`, tags the image for the	35		`gordon push` resolves the route image for `<domain>`, tags the image for the
36	Gordon registry, pushes it, and optionally deploys it.	36		Gordon registry, pushes it, and optionally deploys it.
37		37
		38	+	- For first deploys, prefer `gordon bootstrap`, which creates or updates the route and then pushes and deploys the image.
38	- The registry and repository are derived from the route image on the server.	39		- The registry and repository are derived from the route image on the server.
39	- The version tag defaults to a CI tag ref (like `refs/tags/v1.2.3`) when available,	40		- The version tag defaults to a CI tag ref (like `refs/tags/v1.2.3`) when available,
40	then falls back to `git describe --tags --dirty` (for example	41		then falls back to `git describe --tags --dirty` (for example

@@ -66,6 +67,7 @@ gordon push myapp.example.com --build -f docker/app/Dockerfile
66	### Notes	67		### Notes
67		68
68	- Remote mode required. See [CLI Overview](./index.md) for targeting options.	69		- Remote mode required. See [CLI Overview](./index.md) for targeting options.
		70	+	- `gordon push` still requires the route to already exist so it can resolve the target image.
69	- `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux,	71		- `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux,
70	install the `docker-buildx-plugin` package.	72		install the `docker-buildx-plugin` package.
71		73

M docs/cli/routes.md +43 -2


@@ -12,7 +12,7 @@ Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
12	12		\| Subcommand \| Description \|
13	13		\|------------\|-------------\|
14	14		\| `list` \| List all routes \|
15		-	\| `add` \| Add a new route \|
	15	+	\| `add` \| Create or update a route \|
16	16		\| `remove` \| Remove a route \|
17	17		\| `deploy` \| Deploy a specific route \|
18	18

@@ -24,6 +24,7 @@ List all configured routes.
24	24
25	25		```bash
26	26		gordon routes list
	27	+	gordon routes list --json
27	28		gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
28	29		```
29	30

@@ -37,17 +38,49 @@ api.example.com myapi:v2.1.0 running
37	38		admin.example.com admin-panel:latest stopped
38	39		```
39	40
	41	+	### JSON Output
	42	+
	43	+	```bash
	44	+	gordon routes list --json
	45	+	```
	46	+
	47	+	```json
	48	+	[
	49	+	{
	50	+	"domain": "app.example.com",
	51	+	"image": "myapp:latest",
	52	+	"status": "running"
	53	+	},
	54	+	{
	55	+	"domain": "api.example.com",
	56	+	"image": "myapi:v2.1.0",
	57	+	"status": "running"
	58	+	}
	59	+	]
	60	+	```
	61	+
	62	+	### Options
	63	+
	64	+	\| Option \| Description \|
	65	+	\|--------\|-------------\|
	66	+	\| `--json` \| Output routes as JSON \|
	67	+	\| `--remote` \| Remote Gordon URL \|
	68	+	\| `--token` \| Authentication token for remote \|
	69	+
40	70		---
41	71
42	72		## gordon routes add
43	73
44		-	Add a new route.
	74	+	Create a new route or update an existing route.
45	75
46	76		```bash
47	77		gordon routes add <domain> <image>
48	78		gordon routes add myapp.example.com myapp:latest
49	79		```
50	80
	81	+	If the route already exists, Gordon updates it to the new image instead of failing.
	82	+	The image does not need to be pushed to the Gordon registry before you add the route.
	83	+
51	84		### Arguments
52	85
53	86		\| Argument \| Description \|

@@ -69,10 +102,18 @@ gordon routes add myapp.example.com myapp:latest
69	102		gordon routes add myapp.example.com myapp:latest
70	103		gordon routes add api.example.com myapi:v2.1.0
71	104
	105	+	# Update an existing route
	106	+	gordon routes add myapp.example.com myapp:v2
	107	+
72	108		# Remote (override)
73	109		gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
74	110		```
75	111
	112	+	### Notes
	113	+
	114	+	- `gordon routes add` is idempotent: it creates the route when missing and updates it when present.
	115	+	- You can add the route before the image is pushed. Deploy happens when the image is later available or when you deploy an available image.
	116	+
76	117		---
77	118
78	119		## gordon routes remove


@@ -12,7 +12,7 @@ Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
12		\| Subcommand \| Description \|	12		\| Subcommand \| Description \|
13		\|------------\|-------------\|	13		\|------------\|-------------\|
14		\| `list` \| List all routes \|	14		\| `list` \| List all routes \|
15	-	\| `add` \| Add a new route \|	15	+	\| `add` \| Create or update a route \|
16		\| `remove` \| Remove a route \|	16		\| `remove` \| Remove a route \|
17		\| `deploy` \| Deploy a specific route \|	17		\| `deploy` \| Deploy a specific route \|
18			18

@@ -24,6 +24,7 @@ List all configured routes.
24			24
25		```bash	25		```bash
26		gordon routes list	26		gordon routes list
			27	+	gordon routes list --json
27		gordon routes list --remote https://gordon.mydomain.com --token $TOKEN	28		gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
28		```	29		```
29			30

@@ -37,17 +38,49 @@ api.example.com myapi:v2.1.0 running
37		admin.example.com admin-panel:latest stopped	38		admin.example.com admin-panel:latest stopped
38		```	39		```
39			40
			41	+	### JSON Output
			42	+
			43	+	```bash
			44	+	gordon routes list --json
			45	+	```
			46	+
			47	+	```json
			48	+	[
			49	+	{
			50	+	"domain": "app.example.com",
			51	+	"image": "myapp:latest",
			52	+	"status": "running"
			53	+	},
			54	+	{
			55	+	"domain": "api.example.com",
			56	+	"image": "myapi:v2.1.0",
			57	+	"status": "running"
			58	+	}
			59	+	]
			60	+	```
			61	+
			62	+	### Options
			63	+
			64	+	\| Option \| Description \|
			65	+	\|--------\|-------------\|
			66	+	\| `--json` \| Output routes as JSON \|
			67	+	\| `--remote` \| Remote Gordon URL \|
			68	+	\| `--token` \| Authentication token for remote \|
			69	+
40		---	70		---
41			71
42		## gordon routes add	72		## gordon routes add
43			73
44	-	Add a new route.	74	+	Create a new route or update an existing route.
45			75
46		```bash	76		```bash
47		gordon routes add <domain> <image>	77		gordon routes add <domain> <image>
48		gordon routes add myapp.example.com myapp:latest	78		gordon routes add myapp.example.com myapp:latest
49		```	79		```
50			80
			81	+	If the route already exists, Gordon updates it to the new image instead of failing.
			82	+	The image does not need to be pushed to the Gordon registry before you add the route.
			83	+
51		### Arguments	84		### Arguments
52			85
53		\| Argument \| Description \|	86		\| Argument \| Description \|

@@ -69,10 +102,18 @@ gordon routes add myapp.example.com myapp:latest
69		gordon routes add myapp.example.com myapp:latest	102		gordon routes add myapp.example.com myapp:latest
70		gordon routes add api.example.com myapi:v2.1.0	103		gordon routes add api.example.com myapi:v2.1.0
71			104
			105	+	# Update an existing route
			106	+	gordon routes add myapp.example.com myapp:v2
			107	+
72		# Remote (override)	108		# Remote (override)
73		gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN	109		gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
74		```	110		```
75			111
			112	+	### Notes
			113	+
			114	+	- `gordon routes add` is idempotent: it creates the route when missing and updates it when present.
			115	+	- You can add the route before the image is pushed. Deploy happens when the image is later available or when you deploy an available image.
			116	+
76		---	117		---
77			118
78		## gordon routes remove	119		## gordon routes remove

M docs/cli/secrets.md +26 -0


@@ -39,6 +39,7 @@ gordon secrets list <domain>
39	39
40	40		\| Option \| Description \|
41	41		\|--------\|-------------\|
	42	+	\| `--json` \| Output secrets as JSON \|
42	43		\| `--remote` \| Remote Gordon URL \|
43	44		\| `--token` \| Authentication token for remote \|
44	45

@@ -67,6 +68,31 @@ API_KEY ****
67	68		└─ REDIS_PASSWORD ****
68	69		```
69	70
	71	+	### JSON Output
	72	+
	73	+	```bash
	74	+	gordon secrets list app.mydomain.com --json
	75	+	```
	76	+
	77	+	```json
	78	+	{
	79	+	"domain": "app.mydomain.com",
	80	+	"secrets": {
	81	+	"DATABASE_URL": "****",
	82	+	"API_KEY": "****"
	83	+	},
	84	+	"attachments": {
	85	+	"postgres": {
	86	+	"POSTGRES_USER": "****",
	87	+	"POSTGRES_PASSWORD": "****"
	88	+	},
	89	+	"redis": {
	90	+	"REDIS_PASSWORD": "****"
	91	+	}
	92	+	}
	93	+	}
	94	+	```
	95	+
70	96		---
71	97
72	98		## gordon secrets set


@@ -39,6 +39,7 @@ gordon secrets list <domain>
39		39
40	\| Option \| Description \|	40		\| Option \| Description \|
41	\|--------\|-------------\|	41		\|--------\|-------------\|
		42	+	\| `--json` \| Output secrets as JSON \|
42	\| `--remote` \| Remote Gordon URL \|	43		\| `--remote` \| Remote Gordon URL \|
43	\| `--token` \| Authentication token for remote \|	44		\| `--token` \| Authentication token for remote \|
44		45

@@ -67,6 +68,31 @@ API_KEY ****
67	└─ REDIS_PASSWORD ****	68		└─ REDIS_PASSWORD ****
68	```	69		```
69		70
		71	+	### JSON Output
		72	+
		73	+	```bash
		74	+	gordon secrets list app.mydomain.com --json
		75	+	```
		76	+
		77	+	```json
		78	+	{
		79	+	"domain": "app.mydomain.com",
		80	+	"secrets": {
		81	+	"DATABASE_URL": "****",
		82	+	"API_KEY": "****"
		83	+	},
		84	+	"attachments": {
		85	+	"postgres": {
		86	+	"POSTGRES_USER": "****",
		87	+	"POSTGRES_PASSWORD": "****"
		88	+	},
		89	+	"redis": {
		90	+	"REDIS_PASSWORD": "****"
		91	+	}
		92	+	}
		93	+	}
		94	+	```
		95	+
70	---	96		---
71		97
72	## gordon secrets set	98		## gordon secrets set

M docs/getting-started.md +15 -9


@@ -143,19 +143,25 @@ On your local machine:
143	143		gordon remotes add prod https://gordon.mydomain.com --token <your-token>
144	144		gordon remotes use prod
145	145
146		-	# Build, push, and deploy through Gordon
147		-	gordon push myapp --build --no-confirm
	146	+	# Recommended first deploy path
	147	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
148	148		```
149	149
150	150		What this command does:
151	151
152		-	- `gordon push myapp` resolves the route for `myapp`, chooses a version tag,
153		-	pushes image tags to Gordon's registry, and triggers deploy.
154		-	- `--build` runs `docker buildx build` first, injecting `VERSION` from the tag
155		-	into the build and then pushing both version and `latest` tags. This requires
156		-	Docker with Buildx; a Podman-only setup is not supported for `--build`.
157		-	- `--no-confirm` skips the interactive "Deploy now?" prompt so the deploy runs
158		-	immediately.
	152	+	- `gordon bootstrap` creates or updates the route, applies requested attachments
	153	+	and environment variables, then pushes and deploys the image.
	154	+	- This is the recommended path for first deploys because it does not require the
	155	+	route to exist ahead of time.
	156	+
	157	+	If the route already exists and you only need to push a new image version, use:
	158	+
	159	+	```bash
	160	+	gordon push app.example.com --build --no-confirm
	161	+	```
	162	+
	163	+	`gordon push` still requires the route to already exist so it can resolve the
	164	+	target image.
159	165
160	166		Your app is now live at `https://app.mydomain.com`!
161	167


@@ -143,19 +143,25 @@ On your local machine:
143		gordon remotes add prod https://gordon.mydomain.com --token <your-token>	143		gordon remotes add prod https://gordon.mydomain.com --token <your-token>
144		gordon remotes use prod	144		gordon remotes use prod
145			145
146	-	# Build, push, and deploy through Gordon	146	+	# Recommended first deploy path
147	-	gordon push myapp --build --no-confirm	147	+	gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
148		```	148		```
149			149
150		What this command does:	150		What this command does:
151			151
152	-	- `gordon push myapp` resolves the route for `myapp`, chooses a version tag,	152	+	- `gordon bootstrap` creates or updates the route, applies requested attachments
153	-	pushes image tags to Gordon's registry, and triggers deploy.	153	+	and environment variables, then pushes and deploys the image.
154	-	- `--build` runs `docker buildx build` first, injecting `VERSION` from the tag	154	+	- This is the recommended path for first deploys because it does not require the
155	-	into the build and then pushing both version and `latest` tags. This requires	155	+	route to exist ahead of time.
156	-	Docker with Buildx; a Podman-only setup is not supported for `--build`.	156	+
157	-	- `--no-confirm` skips the interactive "Deploy now?" prompt so the deploy runs	157	+	If the route already exists and you only need to push a new image version, use:
158	-	immediately.	158	+
			159	+	```bash
			160	+	gordon push app.example.com --build --no-confirm
			161	+	```
			162	+
			163	+	`gordon push` still requires the route to already exist so it can resolve the
			164	+	target image.
159			165
160		Your app is now live at `https://app.mydomain.com`!	166		Your app is now live at `https://app.mydomain.com`!
161			167