detached 27c6ff9

docs: split CLI commands.md into separate files per command group

Split the 805-line commands.md into focused documentation files:
- index.md: Overview, quick reference, global options
- serve.md: Server commands (serve, reload, deploy, logs, version)
- auth.md: Authentication commands (token, password)
- routes.md: Route management commands
- attachments.md: Attachment management commands
- secrets.md: Secret management commands
- remotes.md: Remote management commands

This improves navigation and maintainability of CLI documentation.
commit
27c6ff93a68302aa83d8a1c8917bfd4eeed24db6
author
brice · · 2026-01-17 15:29 UTC
parent
50b1179
signature
unsigned
8 files · +1441 -804
Unified
UnifiedSplit
A docs/cli/attachments.md +178 -0
@@ -0,0 +1,178 @@
1+# Attachments Commands
2+
3+Manage attachments on local or remote Gordon instances.
4+
5+## gordon attachments
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all attachments or attachments for a specific target |
12+| `add` | Add an attachment to a domain or network group |
13+| `remove` | Remove an attachment from a domain or network group |
14+
15+### Alias
16+
17+`gordon attach` is an alias for `gordon attachments`:
18+
19+```bash
20+gordon attach list
21+gordon attach add app.example.com postgres:15
22+gordon attach remove app.example.com postgres:15
23+```
24+
25+---
26+
27+## gordon attachments list
28+
29+List all configured attachments.
30+
31+```bash
32+# List all attachments
33+gordon attachments list
34+
35+# List attachments for a specific domain or group
36+gordon attachments list app.example.com
37+gordon attachments list backend
38+
39+# Remote mode
40+gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
41+```
42+
43+### Output
44+
45+```
46+Target Attachments
47+--------------------------------------------------------------------------------
48+app.example.com postgres:15, redis:7-alpine
49+api.example.com postgres:15
50+backend (group) rabbitmq:3-management
51+```
52+
53+---
54+
55+## gordon attachments add
56+
57+Add an attachment to a domain or network group.
58+
59+```bash
60+gordon attachments add <domain-or-group> <image>
61+gordon attachments add app.example.com postgres:15
62+gordon attachments add backend redis:7-alpine
63+```
64+
65+### Arguments
66+
67+| Argument | Description |
68+|----------|-------------|
69+| `<domain-or-group>` | The domain name or network group name |
70+| `<image>` | The container image to attach |
71+
72+### Options
73+
74+| Option | Description |
75+|--------|-------------|
76+| `--remote` | Remote Gordon URL |
77+| `--token` | Authentication token for remote |
78+
79+### Examples
80+
81+```bash
82+# Add database to a domain
83+gordon attachments add app.example.com postgres:15
84+
85+# Add cache to a network group (shared by all domains in the group)
86+gordon attachments add backend redis:7-alpine
87+
88+# Remote
89+gordon attachments add app.example.com postgres:15 --remote https://gordon.mydomain.com --token $TOKEN
90+```
91+
92+---
93+
94+## gordon attachments remove
95+
96+Remove an attachment.
97+
98+```bash
99+gordon attachments remove <domain-or-group> <image>
100+gordon attachments remove app.example.com postgres:15
101+```
102+
103+### Arguments
104+
105+| Argument | Description |
106+|----------|-------------|
107+| `<domain-or-group>` | The domain name or network group name |
108+| `<image>` | The container image to remove |
109+
110+### Options
111+
112+| Option | Description |
113+|--------|-------------|
114+| `--remote` | Remote Gordon URL |
115+| `--token` | Authentication token for remote |
116+
117+### Examples
118+
119+```bash
120+# Remove database from a domain
121+gordon attachments remove app.example.com postgres:15
122+
123+# Remove from network group
124+gordon attachments remove backend redis:7-alpine
125+
126+# Remote
127+gordon attachments remove app.example.com postgres:15 --remote https://gordon.mydomain.com --token $TOKEN
128+```
129+
130+---
131+
132+## Workflow Examples
133+
134+### Add Database and Cache
135+
136+```bash
137+# Add PostgreSQL database
138+gordon attachments add app.example.com postgres:15
139+
140+# Add Redis cache
141+gordon attachments add app.example.com redis:7-alpine
142+
143+# Verify
144+gordon attachments list app.example.com
145+```
146+
147+### Shared Services via Network Groups
148+
149+```bash
150+# First, ensure you have a network group defined in your config:
151+# [network_groups]
152+# "backend" = ["app.example.com", "api.example.com"]
153+
154+# Add shared cache to the group
155+gordon attachments add backend redis:7-alpine
156+
157+# Both app.example.com and api.example.com can now access the shared Redis
158+```
159+
160+### CI/CD Integration
161+
162+```bash
163+# In your CI/CD pipeline
164+export GORDON_REMOTE=https://gordon.mydomain.com
165+export GORDON_TOKEN=$GORDON_TOKEN
166+
167+# Add new attachment
168+gordon attachments add app.example.com elasticsearch:8
169+
170+# Trigger redeploy to pick up the new attachment
171+gordon routes deploy app.example.com
172+```
173+
174+## Related
175+
176+- [CLI Overview](./index.md)
177+- [Attachments Configuration](../config/attachments.md)
178+- [Network Groups](../config/network-groups.md)
@@ -0,0 +1,178 @@
1+# Attachments Commands
2+
3+Manage attachments on local or remote Gordon instances.
4+
5+## gordon attachments
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all attachments or attachments for a specific target |
12+| `add` | Add an attachment to a domain or network group |
13+| `remove` | Remove an attachment from a domain or network group |
14+
15+### Alias
16+
17+`gordon attach` is an alias for `gordon attachments`:
18+
19+```bash
20+gordon attach list
21+gordon attach add app.example.com postgres:15
22+gordon attach remove app.example.com postgres:15
23+```
24+
25+---
26+
27+## gordon attachments list
28+
29+List all configured attachments.
30+
31+```bash
32+# List all attachments
33+gordon attachments list
34+
35+# List attachments for a specific domain or group
36+gordon attachments list app.example.com
37+gordon attachments list backend
38+
39+# Remote mode
40+gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
41+```
42+
43+### Output
44+
45+```
46+Target Attachments
47+--------------------------------------------------------------------------------
48+app.example.com postgres:15, redis:7-alpine
49+api.example.com postgres:15
50+backend (group) rabbitmq:3-management
51+```
52+
53+---
54+
55+## gordon attachments add
56+
57+Add an attachment to a domain or network group.
58+
59+```bash
60+gordon attachments add <domain-or-group> <image>
61+gordon attachments add app.example.com postgres:15
62+gordon attachments add backend redis:7-alpine
63+```
64+
65+### Arguments
66+
67+| Argument | Description |
68+|----------|-------------|
69+| `<domain-or-group>` | The domain name or network group name |
70+| `<image>` | The container image to attach |
71+
72+### Options
73+
74+| Option | Description |
75+|--------|-------------|
76+| `--remote` | Remote Gordon URL |
77+| `--token` | Authentication token for remote |
78+
79+### Examples
80+
81+```bash
82+# Add database to a domain
83+gordon attachments add app.example.com postgres:15
84+
85+# Add cache to a network group (shared by all domains in the group)
86+gordon attachments add backend redis:7-alpine
87+
88+# Remote
89+gordon attachments add app.example.com postgres:15 --remote https://gordon.mydomain.com --token $TOKEN
90+```
91+
92+---
93+
94+## gordon attachments remove
95+
96+Remove an attachment.
97+
98+```bash
99+gordon attachments remove <domain-or-group> <image>
100+gordon attachments remove app.example.com postgres:15
101+```
102+
103+### Arguments
104+
105+| Argument | Description |
106+|----------|-------------|
107+| `<domain-or-group>` | The domain name or network group name |
108+| `<image>` | The container image to remove |
109+
110+### Options
111+
112+| Option | Description |
113+|--------|-------------|
114+| `--remote` | Remote Gordon URL |
115+| `--token` | Authentication token for remote |
116+
117+### Examples
118+
119+```bash
120+# Remove database from a domain
121+gordon attachments remove app.example.com postgres:15
122+
123+# Remove from network group
124+gordon attachments remove backend redis:7-alpine
125+
126+# Remote
127+gordon attachments remove app.example.com postgres:15 --remote https://gordon.mydomain.com --token $TOKEN
128+```
129+
130+---
131+
132+## Workflow Examples
133+
134+### Add Database and Cache
135+
136+```bash
137+# Add PostgreSQL database
138+gordon attachments add app.example.com postgres:15
139+
140+# Add Redis cache
141+gordon attachments add app.example.com redis:7-alpine
142+
143+# Verify
144+gordon attachments list app.example.com
145+```
146+
147+### Shared Services via Network Groups
148+
149+```bash
150+# First, ensure you have a network group defined in your config:
151+# [network_groups]
152+# "backend" = ["app.example.com", "api.example.com"]
153+
154+# Add shared cache to the group
155+gordon attachments add backend redis:7-alpine
156+
157+# Both app.example.com and api.example.com can now access the shared Redis
158+```
159+
160+### CI/CD Integration
161+
162+```bash
163+# In your CI/CD pipeline
164+export GORDON_REMOTE=https://gordon.mydomain.com
165+export GORDON_TOKEN=$GORDON_TOKEN
166+
167+# Add new attachment
168+gordon attachments add app.example.com elasticsearch:8
169+
170+# Trigger redeploy to pick up the new attachment
171+gordon routes deploy app.example.com
172+```
173+
174+## Related
175+
176+- [CLI Overview](./index.md)
177+- [Attachments Configuration](../config/attachments.md)
178+- [Network Groups](../config/network-groups.md)
A docs/cli/auth.md +268 -0
@@ -0,0 +1,268 @@
1+# Authentication Commands
2+
3+Manage registry authentication tokens and passwords.
4+
5+## gordon auth
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `token generate` | Generate a new JWT token |
12+| `token list` | List all stored tokens |
13+| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
14+| `password hash` | Generate bcrypt password hash |
15+| `internal` | Show internal registry credentials |
16+
17+---
18+
19+## gordon auth token generate
20+
21+Generate a new JWT authentication token for registry access.
22+
23+```bash
24+gordon auth token generate --subject <name> [options]
25+```
26+
27+### Options
28+
29+| Option | Default | Description |
30+|--------|---------|-------------|
31+| `--subject` | (required) | Username/subject for the token |
32+| `--scopes` | `push,pull` | Comma-separated scopes |
33+| `--expiry` | `30d` | Duration until expiry (0 = never) |
34+| `-c, --config` | Auto | Path to config file |
35+
36+### Duration Format
37+
38+Supports human-friendly duration units:
39+
40+| Unit | Description | Example |
41+|------|-------------|---------|
42+| `d` | Days (24 hours) | `30d` |
43+| `w` | Weeks (7 days) | `2w` |
44+| `M` | Months (30 days) | `6M` |
45+| `y` | Years (365 days) | `1y` |
46+
47+Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
48+
49+Standard Go durations also work: `24h`, `30m`, `1h30m`
50+
51+### Examples
52+
53+```bash
54+# CI token that never expires
55+gordon auth token generate --subject github-actions --expiry 0
56+
57+# Read-only token for 30 days
58+gordon auth token generate --subject reader --scopes pull --expiry 30d
59+
60+# Push-only token for 1 year
61+gordon auth token generate --subject builder --scopes push --expiry 1y
62+
63+# Temporary token (24 hours)
64+gordon auth token generate --subject temp --expiry 24h
65+
66+# Token for 6 months
67+gordon auth token generate --subject deploy --expiry 6M
68+```
69+
70+### Output
71+
72+```
73+Token generated successfully!
74+Subject: github-actions
75+Scopes: push, pull
76+Expiry: never
77+
78+Token (use as password with docker login):
79+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
80+
81+Usage: docker login -u github-actions -p <token> <registry>
82+```
83+
84+---
85+
86+## gordon auth token list
87+
88+List all stored authentication tokens.
89+
90+```bash
91+gordon auth token list [options]
92+```
93+
94+### Output
95+
96+```
97+ID Subject Expires Revoked
98+------------------------------------------------------------------------------------------
99+a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
100+b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
101+c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
102+```
103+
104+---
105+
106+## gordon auth token revoke
107+
108+Revoke a token by its ID.
109+
110+```bash
111+gordon auth token revoke <token-id> [options]
112+gordon auth token revoke --all # Revoke all tokens
113+```
114+
115+### Example
116+
117+```bash
118+gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
119+```
120+
121+### Output
122+
123+```
124+Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
125+```
126+
127+---
128+
129+## gordon auth password hash
130+
131+Generate a bcrypt hash for password authentication.
132+
133+```bash
134+gordon auth password hash
135+```
136+
137+Interactively prompts for a password and outputs the bcrypt hash.
138+
139+### Output
140+
141+```
142+Enter password: ********
143+
144+Bcrypt hash (store in your secrets backend):
145+$2a$10$N9qo8uLOickgx2ZMRZoMye...
146+
147+Then reference the path in your config:
148+ [auth]
149+ type = "password"
150+ password_hash = "gordon/auth/password_hash"
151+```
152+
153+---
154+
155+## gordon auth internal
156+
157+Display the auto-generated internal registry credentials.
158+
159+```bash
160+gordon auth internal
161+```
162+
163+Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
164+
165+### Output
166+
167+```
168+Internal Registry Credentials
169+==============================
170+Username: gordon-internal
171+Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
172+
173+Usage:
174+ docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
175+```
176+
177+### Notes
178+
179+- Credentials are regenerated each time Gordon starts
180+- Only available while Gordon is running
181+- Used for manual `docker pull` from the local registry during debugging
182+
183+### Use Cases
184+
185+- Debugging image pull failures
186+- Manual recovery after deployment issues
187+- Inspecting images in the local registry
188+
189+---
190+
191+## Token Scopes
192+
193+| Scope | Permission |
194+|-------|------------|
195+| `push` | Push images to registry |
196+| `pull` | Pull images from registry |
197+| `push,pull` | Both push and pull (default) |
198+
199+## Token Expiry Formats
200+
201+| Format | Duration |
202+|--------|----------|
203+| `0` | Never expires |
204+| `24h` | 24 hours |
205+| `720h` | 30 days |
206+| `8760h` | 1 year |
207+
208+---
209+
210+## Workflow Examples
211+
212+### CI/CD Setup
213+
214+```bash
215+# Generate token for CI
216+gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
217+
218+# Save token as CI secret
219+# GitHub: Settings → Secrets → New repository secret
220+# GitLab: Settings → CI/CD → Variables
221+```
222+
223+### Docker Login
224+
225+```bash
226+# Using generated token
227+docker login -u ci-bot -p <token> registry.mydomain.com
228+
229+# In CI/CD
230+echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
231+```
232+
233+### Token Rotation
234+
235+```bash
236+# Generate new token
237+gordon auth token generate --subject ci-bot --expiry 0
238+
239+# Update CI secrets with new token
240+
241+# Revoke old token
242+gordon auth token revoke <old-token-id>
243+```
244+
245+### Password Setup
246+
247+```bash
248+# Generate hash
249+gordon auth password hash
250+# Enter: mypassword
251+
252+# Store in pass
253+pass insert gordon/auth/password_hash
254+# Paste: $2a$10$...
255+
256+# Configure gordon.toml
257+[auth]
258+enabled = true
259+type = "password"
260+secrets_backend = "pass"
261+username = "deploy"
262+password_hash = "gordon/auth/password_hash"
263+```
264+
265+## Related
266+
267+- [CLI Overview](./index.md)
268+- [Authentication Configuration](../config/auth.md)
@@ -0,0 +1,268 @@
1+# Authentication Commands
2+
3+Manage registry authentication tokens and passwords.
4+
5+## gordon auth
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `token generate` | Generate a new JWT token |
12+| `token list` | List all stored tokens |
13+| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
14+| `password hash` | Generate bcrypt password hash |
15+| `internal` | Show internal registry credentials |
16+
17+---
18+
19+## gordon auth token generate
20+
21+Generate a new JWT authentication token for registry access.
22+
23+```bash
24+gordon auth token generate --subject <name> [options]
25+```
26+
27+### Options
28+
29+| Option | Default | Description |
30+|--------|---------|-------------|
31+| `--subject` | (required) | Username/subject for the token |
32+| `--scopes` | `push,pull` | Comma-separated scopes |
33+| `--expiry` | `30d` | Duration until expiry (0 = never) |
34+| `-c, --config` | Auto | Path to config file |
35+
36+### Duration Format
37+
38+Supports human-friendly duration units:
39+
40+| Unit | Description | Example |
41+|------|-------------|---------|
42+| `d` | Days (24 hours) | `30d` |
43+| `w` | Weeks (7 days) | `2w` |
44+| `M` | Months (30 days) | `6M` |
45+| `y` | Years (365 days) | `1y` |
46+
47+Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
48+
49+Standard Go durations also work: `24h`, `30m`, `1h30m`
50+
51+### Examples
52+
53+```bash
54+# CI token that never expires
55+gordon auth token generate --subject github-actions --expiry 0
56+
57+# Read-only token for 30 days
58+gordon auth token generate --subject reader --scopes pull --expiry 30d
59+
60+# Push-only token for 1 year
61+gordon auth token generate --subject builder --scopes push --expiry 1y
62+
63+# Temporary token (24 hours)
64+gordon auth token generate --subject temp --expiry 24h
65+
66+# Token for 6 months
67+gordon auth token generate --subject deploy --expiry 6M
68+```
69+
70+### Output
71+
72+```
73+Token generated successfully!
74+Subject: github-actions
75+Scopes: push, pull
76+Expiry: never
77+
78+Token (use as password with docker login):
79+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
80+
81+Usage: docker login -u github-actions -p <token> <registry>
82+```
83+
84+---
85+
86+## gordon auth token list
87+
88+List all stored authentication tokens.
89+
90+```bash
91+gordon auth token list [options]
92+```
93+
94+### Output
95+
96+```
97+ID Subject Expires Revoked
98+------------------------------------------------------------------------------------------
99+a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
100+b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
101+c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
102+```
103+
104+---
105+
106+## gordon auth token revoke
107+
108+Revoke a token by its ID.
109+
110+```bash
111+gordon auth token revoke <token-id> [options]
112+gordon auth token revoke --all # Revoke all tokens
113+```
114+
115+### Example
116+
117+```bash
118+gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
119+```
120+
121+### Output
122+
123+```
124+Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
125+```
126+
127+---
128+
129+## gordon auth password hash
130+
131+Generate a bcrypt hash for password authentication.
132+
133+```bash
134+gordon auth password hash
135+```
136+
137+Interactively prompts for a password and outputs the bcrypt hash.
138+
139+### Output
140+
141+```
142+Enter password: ********
143+
144+Bcrypt hash (store in your secrets backend):
145+$2a$10$N9qo8uLOickgx2ZMRZoMye...
146+
147+Then reference the path in your config:
148+ [auth]
149+ type = "password"
150+ password_hash = "gordon/auth/password_hash"
151+```
152+
153+---
154+
155+## gordon auth internal
156+
157+Display the auto-generated internal registry credentials.
158+
159+```bash
160+gordon auth internal
161+```
162+
163+Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
164+
165+### Output
166+
167+```
168+Internal Registry Credentials
169+==============================
170+Username: gordon-internal
171+Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
172+
173+Usage:
174+ docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
175+```
176+
177+### Notes
178+
179+- Credentials are regenerated each time Gordon starts
180+- Only available while Gordon is running
181+- Used for manual `docker pull` from the local registry during debugging
182+
183+### Use Cases
184+
185+- Debugging image pull failures
186+- Manual recovery after deployment issues
187+- Inspecting images in the local registry
188+
189+---
190+
191+## Token Scopes
192+
193+| Scope | Permission |
194+|-------|------------|
195+| `push` | Push images to registry |
196+| `pull` | Pull images from registry |
197+| `push,pull` | Both push and pull (default) |
198+
199+## Token Expiry Formats
200+
201+| Format | Duration |
202+|--------|----------|
203+| `0` | Never expires |
204+| `24h` | 24 hours |
205+| `720h` | 30 days |
206+| `8760h` | 1 year |
207+
208+---
209+
210+## Workflow Examples
211+
212+### CI/CD Setup
213+
214+```bash
215+# Generate token for CI
216+gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
217+
218+# Save token as CI secret
219+# GitHub: Settings → Secrets → New repository secret
220+# GitLab: Settings → CI/CD → Variables
221+```
222+
223+### Docker Login
224+
225+```bash
226+# Using generated token
227+docker login -u ci-bot -p <token> registry.mydomain.com
228+
229+# In CI/CD
230+echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
231+```
232+
233+### Token Rotation
234+
235+```bash
236+# Generate new token
237+gordon auth token generate --subject ci-bot --expiry 0
238+
239+# Update CI secrets with new token
240+
241+# Revoke old token
242+gordon auth token revoke <old-token-id>
243+```
244+
245+### Password Setup
246+
247+```bash
248+# Generate hash
249+gordon auth password hash
250+# Enter: mypassword
251+
252+# Store in pass
253+pass insert gordon/auth/password_hash
254+# Paste: $2a$10$...
255+
256+# Configure gordon.toml
257+[auth]
258+enabled = true
259+type = "password"
260+secrets_backend = "pass"
261+username = "deploy"
262+password_hash = "gordon/auth/password_hash"
263+```
264+
265+## Related
266+
267+- [CLI Overview](./index.md)
268+- [Authentication Configuration](../config/auth.md)
D docs/cli/commands.md +0 -804
@@ -1,804 +0,0 @@
1-# CLI Commands
2-
3-Gordon provides a command-line interface for server management, deployment, and authentication.
4-
5-## Commands Overview
6-
7-| Command | Description |
8-|---------|-------------|
9-| `gordon serve` | Start the Gordon server |
10-| `gordon reload` | Reload configuration and sync containers |
11-| `gordon deploy` | Manually deploy or redeploy a specific route |
12-| `gordon logs` | Display Gordon process or container logs |
13-| `gordon version` | Print version information |
14-| `gordon auth` | Manage registry authentication |
15-| `gordon routes` | Manage routes (local or remote) |
16-| `gordon attachments` | Manage attachments (local or remote) |
17-| `gordon secrets` | Manage secrets (local or remote) |
18-| `gordon remotes` | Manage saved remote Gordon instances |
19-
20-## Quick Reference
21-
22-```bash
23-# Start Gordon
24-gordon serve
25-gordon serve --config /path/to/config.toml
26-
27-# Reload configuration
28-gordon reload
29-
30-# Deploy a specific route
31-gordon deploy myapp.example.com
32-
33-# View logs
34-gordon logs # Gordon process logs
35-gordon logs -f # Follow process logs
36-gordon logs -n 100 # Last 100 lines
37-gordon logs myapp.local # Container logs for myapp.local
38-gordon logs myapp.local -f # Follow container logs
39-
40-# Check version
41-gordon version
42-
43-# Authentication
44-gordon auth token generate --subject ci-bot --expiry 0
45-gordon auth token list
46-gordon auth token revoke <token-id>
47-gordon auth password hash
48-gordon auth internal
49-```
50-
51-## Global Options
52-
53-| Option | Description |
54-|--------|-------------|
55-| `-c, --config` | Path to configuration file |
56-| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
57-| `--token` | Authentication token for remote |
58-
59-### Remote Targeting
60-
61-The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
62-
63-**Important:** The remote URL must be the `gordon_domain` configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.
64-
65-```bash
66-# Using flags (use the gordon_domain from remote Gordon config)
67-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
68-
69-# Using environment variables
70-export GORDON_REMOTE=https://gordon.mydomain.com
71-export GORDON_TOKEN=$TOKEN
72-gordon routes list
73-```
74-
75----
76-
77-## gordon serve
78-
79-Start the Gordon server with registry and proxy components.
80-
81-### Synopsis
82-
83-```bash
84-gordon serve [options]
85-```
86-
87-### Options
88-
89-| Option | Short | Default | Description |
90-|--------|-------|---------|-------------|
91-| `--config` | `-c` | Auto-detected | Path to configuration file |
92-
93-### Description
94-
95-Starts the Gordon server, which includes:
96-
97-- **Container Registry** - Receives image pushes on the registry port
98-- **HTTP Proxy** - Routes traffic to containers on the proxy port
99-- **Event Bus** - Coordinates deployments and updates
100-- **Config Watcher** - Monitors configuration file for changes
101-
102-### Configuration File Detection
103-
104-Gordon looks for configuration in this order:
105-
106-1. Path specified with `--config`
107-2. `/etc/gordon/gordon.toml`
108-3. `~/.config/gordon/gordon.toml`
109-4. `./gordon.toml`
110-
111-### First Run
112-
113-On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
114-
115-```bash
116-# First run - creates default config
117-gordon serve
118-# Edit the config, then restart
119-```
120-
121-### Examples
122-
123-```bash
124-# Basic start
125-gordon serve
126-
127-# With custom config
128-gordon serve --config /path/to/gordon.toml
129-gordon serve -c ./my-config.toml
130-
131-# With environment override
132-GORDON_SERVER_PORT=8080 gordon serve
133-GORDON_LOGGING_LEVEL=debug gordon serve
134-```
135-
136-### Signals
137-
138-Gordon responds to these signals:
139-
140-| Signal | Action |
141-|--------|--------|
142-| `SIGTERM` | Graceful shutdown |
143-| `SIGINT` | Graceful shutdown (Ctrl+C) |
144-| `SIGUSR1` | Reload configuration |
145-| `SIGUSR2` | Manual deploy (used by `gordon deploy`) |
146-
147-### Running with systemd
148-
149-```bash
150-# Create user service
151-mkdir -p ~/.config/systemd/user
152-cat > ~/.config/systemd/user/gordon.service <<EOF
153-[Unit]
154-Description=Gordon Container Platform
155-
156-[Service]
157-Type=simple
158-Restart=always
159-ExecStart=/usr/local/bin/gordon serve
160-
161-[Install]
162-WantedBy=default.target
163-EOF
164-
165-# Enable and start
166-systemctl --user daemon-reload
167-systemctl --user enable --now gordon
168-sudo loginctl enable-linger $USER
169-```
170-
171-### Startup Sequence
172-
173-1. Load configuration
174-2. Initialize logger
175-3. Create PID file
176-4. Connect to Docker/Podman runtime
177-5. Create storage directories
178-6. Initialize services (registry, proxy, auth)
179-7. Register event handlers
180-8. Start config file watcher
181-9. Sync existing containers
182-10. Start HTTP servers
183-
184-### Shutdown Sequence
185-
186-1. Receive shutdown signal
187-2. Stop accepting new requests
188-3. Complete in-flight requests
189-4. Stop managed containers (if configured)
190-5. Remove PID file
191-6. Exit
192-
193----
194-
195-## gordon reload
196-
197-Reload configuration and sync containers to match.
198-
199-### Synopsis
200-
201-```bash
202-gordon reload
203-```
204-
205-### Description
206-
207-Sends `SIGUSR1` to the running Gordon process, triggering:
208-
209-- Configuration file reload
210-- Route synchronization
211-- Deployment of containers for routes missing containers
212-- Attachment deployment
213-
214-### Example
215-
216-```bash
217-# After editing gordon.toml, apply changes without restart
218-vim ~/.config/gordon/gordon.toml
219-gordon reload
220-```
221-
222----
223-
224-## gordon deploy
225-
226-Manually deploy or redeploy a specific route.
227-
228-### Synopsis
229-
230-```bash
231-gordon deploy <domain> [options]
232-```
233-
234-### Arguments
235-
236-| Argument | Description |
237-|----------|-------------|
238-| `<domain>` | The domain name of the route to deploy (required) |
239-
240-### Options
241-
242-| Option | Description |
243-|--------|-------------|
244-| `--remote` | Remote Gordon URL |
245-| `--token` | Authentication token for remote |
246-
247-### Description
248-
249-**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
250-
251-**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
252-
253-Both modes trigger:
254-
255-- Fresh image pull (always pulls latest, ignoring cache)
256-- Container redeployment for the specified route
257-
258-### Examples
259-
260-```bash
261-# Local deployment
262-gordon deploy myapp.example.com
263-gordon deploy api.example.com
264-
265-# Remote deployment
266-gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
267-```
268-
269-### Use Cases
270-
271-- Recover from a failed deployment
272-- Force redeploy without pushing a new image
273-- Manual deployment when automatic deploy didn't trigger
274-- Trigger deployments on remote Gordon instances from CI/CD
275-
276----
277-
278-## gordon logs
279-
280-Display Gordon process logs or container logs.
281-
282-### Synopsis
283-
284-```bash
285-gordon logs [domain] [options]
286-```
287-
288-### Arguments
289-
290-| Argument | Description |
291-|----------|-------------|
292-| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
293-
294-### Options
295-
296-| Option | Short | Default | Description |
297-|--------|-------|---------|-------------|
298-| `--config` | `-c` | Auto | Path to config file |
299-| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
300-| `--lines` | `-n` | 50 | Number of lines to show |
301-| `--remote` | | | Remote Gordon URL |
302-| `--token` | | | Authentication token for remote |
303-
304-### Examples
305-
306-```bash
307-# Gordon process logs
308-gordon logs # Last 50 lines
309-gordon logs -f # Follow logs
310-gordon logs -n 100 # Last 100 lines
311-gordon logs -f -n 200 # Follow, starting from last 200 lines
312-
313-# Container logs
314-gordon logs myapp.local # Last 50 lines from container
315-gordon logs myapp.local -f # Follow container logs
316-gordon logs myapp.local -n 100 # Last 100 lines from container
317-
318-# Remote mode
319-gordon logs --remote https://gordon.mydomain.com --token $TOKEN
320-gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN
321-```
322-
323-### Log Locations
324-
325-```bash
326-# Using gordon logs
327-gordon logs -f
328-
329-# Direct file access
330-tail -f ~/.gordon/logs/gordon.log
331-
332-# With systemd
333-journalctl --user -u gordon -f
334-
335-# Container logs via docker (local alternative)
336-docker logs --tail 50 myapp.local
337-docker logs -f myapp.local
338-```
339-
340----
341-
342-## gordon version
343-
344-Print version information.
345-
346-### Synopsis
347-
348-```bash
349-gordon version
350-```
351-
352-### Output
353-
354-```
355-Gordon v2.0.0
356-Commit: abc1234
357-Build Date: 2024-01-15
358-```
359-
360----
361-
362-## gordon auth
363-
364-Manage registry authentication tokens and passwords.
365-
366-### Subcommands
367-
368-| Subcommand | Description |
369-|------------|-------------|
370-| `token generate` | Generate a new JWT token |
371-| `token list` | List all stored tokens |
372-| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
373-| `password hash` | Generate bcrypt password hash |
374-| `internal` | Show internal registry credentials |
375-
376-### gordon auth token generate
377-
378-Generate a new JWT authentication token for registry access.
379-
380-```bash
381-gordon auth token generate --subject <name> [options]
382-```
383-
384-**Options:**
385-
386-| Option | Default | Description |
387-|--------|---------|-------------|
388-| `--subject` | (required) | Username/subject for the token |
389-| `--scopes` | `push,pull` | Comma-separated scopes |
390-| `--expiry` | `30d` | Duration until expiry (0 = never) |
391-| `-c, --config` | Auto | Path to config file |
392-
393-**Duration format:**
394-
395-Supports human-friendly duration units:
396-
397-| Unit | Description | Example |
398-|------|-------------|---------|
399-| `d` | Days (24 hours) | `30d` |
400-| `w` | Weeks (7 days) | `2w` |
401-| `M` | Months (30 days) | `6M` |
402-| `y` | Years (365 days) | `1y` |
403-
404-Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
405-
406-Standard Go durations also work: `24h`, `30m`, `1h30m`
407-
408-**Examples:**
409-
410-```bash
411-# CI token that never expires
412-gordon auth token generate --subject github-actions --expiry 0
413-
414-# Read-only token for 30 days
415-gordon auth token generate --subject reader --scopes pull --expiry 30d
416-
417-# Push-only token for 1 year
418-gordon auth token generate --subject builder --scopes push --expiry 1y
419-
420-# Temporary token (24 hours)
421-gordon auth token generate --subject temp --expiry 24h
422-
423-# Token for 6 months
424-gordon auth token generate --subject deploy --expiry 6M
425-```
426-
427-**Output:**
428-
429-```
430-Token generated successfully!
431-Subject: github-actions
432-Scopes: push, pull
433-Expiry: never
434-
435-Token (use as password with docker login):
436-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
437-
438-Usage: docker login -u github-actions -p <token> <registry>
439-```
440-
441-### gordon auth token list
442-
443-List all stored authentication tokens.
444-
445-```bash
446-gordon auth token list [options]
447-```
448-
449-**Output:**
450-
451-```
452-ID Subject Expires Revoked
453-------------------------------------------------------------------------------------------
454-a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
455-b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
456-c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
457-```
458-
459-### gordon auth token revoke
460-
461-Revoke a token by its ID.
462-
463-```bash
464-gordon auth token revoke <token-id> [options]
465-```
466-
467-**Example:**
468-
469-```bash
470-gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
471-```
472-
473-**Output:**
474-
475-```
476-Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
477-```
478-
479-### gordon auth password hash
480-
481-Generate a bcrypt hash for password authentication.
482-
483-```bash
484-gordon auth password hash
485-```
486-
487-Interactively prompts for a password and outputs the bcrypt hash.
488-
489-**Output:**
490-
491-```
492-Enter password: ********
493-
494-Bcrypt hash (store in your secrets backend):
495-$2a$10$N9qo8uLOickgx2ZMRZoMye...
496-
497-Then reference the path in your config:
498- [auth]
499- type = "password"
500- password_hash = "gordon/auth/password_hash"
501-```
502-
503-### gordon auth internal
504-
505-Display the auto-generated internal registry credentials.
506-
507-```bash
508-gordon auth internal
509-```
510-
511-Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
512-
513-**Output:**
514-
515-```
516-Internal Registry Credentials
517-==============================
518-Username: gordon-internal
519-Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
520-
521-Usage:
522- docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
523-```
524-
525-**Notes:**
526-- Credentials are regenerated each time Gordon starts
527-- Only available while Gordon is running
528-- Used for manual `docker pull` from the local registry during debugging
529-
530-**Use cases:**
531-- Debugging image pull failures
532-- Manual recovery after deployment issues
533-- Inspecting images in the local registry
534-
535----
536-
537-## Token Scopes
538-
539-| Scope | Permission |
540-|-------|------------|
541-| `push` | Push images to registry |
542-| `pull` | Pull images from registry |
543-| `push,pull` | Both push and pull (default) |
544-
545-## Token Expiry Formats
546-
547-| Format | Duration |
548-|--------|----------|
549-| `0` | Never expires |
550-| `24h` | 24 hours |
551-| `720h` | 30 days |
552-| `8760h` | 1 year |
553-
554----
555-
556-## Workflow Examples
557-
558-### CI/CD Setup
559-
560-```bash
561-# Generate token for CI
562-gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
563-
564-# Save token as CI secret
565-# GitHub: Settings → Secrets → New repository secret
566-# GitLab: Settings → CI/CD → Variables
567-```
568-
569-### Docker Login
570-
571-```bash
572-# Using generated token
573-docker login -u ci-bot -p <token> registry.mydomain.com
574-
575-# In CI/CD
576-echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
577-```
578-
579-### Token Rotation
580-
581-```bash
582-# Generate new token
583-gordon auth token generate --subject ci-bot --expiry 0
584-
585-# Update CI secrets with new token
586-
587-# Revoke old token
588-gordon auth token revoke <old-token-id>
589-```
590-
591-### Password Setup
592-
593-```bash
594-# Generate hash
595-gordon auth password hash
596-# Enter: mypassword
597-
598-# Store in pass
599-pass insert gordon/auth/password_hash
600-# Paste: $2a$10$...
601-
602-# Configure gordon.toml
603-[auth]
604-enabled = true
605-type = "password"
606-secrets_backend = "pass"
607-username = "deploy"
608-password_hash = "gordon/auth/password_hash"
609-```
610-
611----
612-
613-## gordon routes
614-
615-Manage routes on local or remote Gordon instances.
616-
617-### Subcommands
618-
619-| Subcommand | Description |
620-|------------|-------------|
621-| `list` | List all routes |
622-| `add` | Add a new route |
623-| `remove` | Remove a route |
624-| `deploy` | Deploy a specific route |
625-
626-### gordon routes list
627-
628-List all configured routes.
629-
630-```bash
631-gordon routes list
632-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
633-```
634-
635-### gordon routes add
636-
637-Add a new route.
638-
639-```bash
640-gordon routes add <domain> <image>
641-gordon routes add myapp.example.com myapp:latest
642-```
643-
644-### gordon routes remove
645-
646-Remove a route.
647-
648-```bash
649-gordon routes remove <domain>
650-gordon routes remove myapp.example.com
651-```
652-
653-### gordon routes deploy
654-
655-Deploy or redeploy a specific route.
656-
657-```bash
658-gordon routes deploy <domain>
659-gordon routes deploy myapp.example.com
660-```
661-
662----
663-
664-## gordon attachments
665-
666-Manage attachments on local or remote Gordon instances.
667-
668-### Subcommands
669-
670-| Subcommand | Description |
671-|------------|-------------|
672-| `list` | List all attachments or attachments for a specific target |
673-| `add` | Add an attachment to a domain or network group |
674-| `remove` | Remove an attachment from a domain or network group |
675-
676-### gordon attachments list
677-
678-List all configured attachments.
679-
680-```bash
681-# List all attachments
682-gordon attachments list
683-
684-# List attachments for a specific domain or group
685-gordon attachments list app.example.com
686-gordon attachments list backend
687-
688-# Remote mode
689-gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
690-```
691-
692-### gordon attachments add
693-
694-Add an attachment to a domain or network group.
695-
696-```bash
697-gordon attachments add <domain-or-group> <image>
698-gordon attachments add app.example.com postgres:15
699-gordon attachments add backend redis:7-alpine
700-```
701-
702-### gordon attachments remove
703-
704-Remove an attachment.
705-
706-```bash
707-gordon attachments remove <domain-or-group> <image>
708-gordon attachments remove app.example.com postgres:15
709-```
710-
711-### Alias
712-
713-`gordon attach` is an alias for `gordon attachments`:
714-
715-```bash
716-gordon attach list
717-gordon attach add app.example.com postgres:15
718-gordon attach remove app.example.com postgres:15
719-```
720-
721----
722-
723-## gordon secrets
724-
725-Manage secrets on local or remote Gordon instances.
726-
727-### Subcommands
728-
729-| Subcommand | Description |
730-|------------|-------------|
731-| `list` | List all secrets for a domain |
732-| `set` | Set a secret value |
733-| `remove` | Remove a secret |
734-
735-### Examples
736-
737-```bash
738-# Local mode (reads/writes secrets directly)
739-gordon secrets list myapp.local
740-gordon secrets set myapp.local DATABASE_URL "postgres://..."
741-gordon secrets remove myapp.local DATABASE_URL
742-
743-# Remote mode
744-gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
745-gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote ... --token ...
746-gordon secrets remove myapp.local DATABASE_URL --remote ... --token ...
747-```
748-
749----
750-
751-## gordon remotes
752-
753-Manage saved remote Gordon instances for easier CLI usage.
754-
755-### Subcommands
756-
757-| Subcommand | Description |
758-|------------|-------------|
759-| `list` | List saved remotes |
760-| `add` | Add a new remote |
761-| `remove` | Remove a saved remote |
762-| `use` | Set active remote |
763-
764-### Examples
765-
766-```bash
767-# Add a remote
768-gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
769-
770-# List saved remotes
771-gordon remotes list
772-
773-# Set active remote
774-gordon remotes use prod
775-
776-# Now use without --remote flag
777-gordon routes list
778-```
779-
780----
781-
782-## Exit Codes
783-
784-| Code | Meaning |
785-|------|---------|
786-| 0 | Success |
787-| 1 | General error |
788-| 2 | Configuration error |
789-
790-## Environment Variables
791-
792-Gordon reads configuration from environment variables:
793-
794-```bash
795-GORDON_SERVER_PORT=8080 gordon serve
796-GORDON_LOGGING_LEVEL=debug gordon serve
797-```
798-
799-Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
800-
801-## Related
802-
803-- [Core Concepts](../concepts.md)
804-- [Configuration Reference](../config/index.md)
@@ -1,804 +0,0 @@
1-# CLI Commands
2-
3-Gordon provides a command-line interface for server management, deployment, and authentication.
4-
5-## Commands Overview
6-
7-| Command | Description |
8-|---------|-------------|
9-| `gordon serve` | Start the Gordon server |
10-| `gordon reload` | Reload configuration and sync containers |
11-| `gordon deploy` | Manually deploy or redeploy a specific route |
12-| `gordon logs` | Display Gordon process or container logs |
13-| `gordon version` | Print version information |
14-| `gordon auth` | Manage registry authentication |
15-| `gordon routes` | Manage routes (local or remote) |
16-| `gordon attachments` | Manage attachments (local or remote) |
17-| `gordon secrets` | Manage secrets (local or remote) |
18-| `gordon remotes` | Manage saved remote Gordon instances |
19-
20-## Quick Reference
21-
22-```bash
23-# Start Gordon
24-gordon serve
25-gordon serve --config /path/to/config.toml
26-
27-# Reload configuration
28-gordon reload
29-
30-# Deploy a specific route
31-gordon deploy myapp.example.com
32-
33-# View logs
34-gordon logs # Gordon process logs
35-gordon logs -f # Follow process logs
36-gordon logs -n 100 # Last 100 lines
37-gordon logs myapp.local # Container logs for myapp.local
38-gordon logs myapp.local -f # Follow container logs
39-
40-# Check version
41-gordon version
42-
43-# Authentication
44-gordon auth token generate --subject ci-bot --expiry 0
45-gordon auth token list
46-gordon auth token revoke <token-id>
47-gordon auth password hash
48-gordon auth internal
49-```
50-
51-## Global Options
52-
53-| Option | Description |
54-|--------|-------------|
55-| `-c, --config` | Path to configuration file |
56-| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
57-| `--token` | Authentication token for remote |
58-
59-### Remote Targeting
60-
61-The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
62-
63-**Important:** The remote URL must be the `gordon_domain` configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.
64-
65-```bash
66-# Using flags (use the gordon_domain from remote Gordon config)
67-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
68-
69-# Using environment variables
70-export GORDON_REMOTE=https://gordon.mydomain.com
71-export GORDON_TOKEN=$TOKEN
72-gordon routes list
73-```
74-
75----
76-
77-## gordon serve
78-
79-Start the Gordon server with registry and proxy components.
80-
81-### Synopsis
82-
83-```bash
84-gordon serve [options]
85-```
86-
87-### Options
88-
89-| Option | Short | Default | Description |
90-|--------|-------|---------|-------------|
91-| `--config` | `-c` | Auto-detected | Path to configuration file |
92-
93-### Description
94-
95-Starts the Gordon server, which includes:
96-
97-- **Container Registry** - Receives image pushes on the registry port
98-- **HTTP Proxy** - Routes traffic to containers on the proxy port
99-- **Event Bus** - Coordinates deployments and updates
100-- **Config Watcher** - Monitors configuration file for changes
101-
102-### Configuration File Detection
103-
104-Gordon looks for configuration in this order:
105-
106-1. Path specified with `--config`
107-2. `/etc/gordon/gordon.toml`
108-3. `~/.config/gordon/gordon.toml`
109-4. `./gordon.toml`
110-
111-### First Run
112-
113-On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
114-
115-```bash
116-# First run - creates default config
117-gordon serve
118-# Edit the config, then restart
119-```
120-
121-### Examples
122-
123-```bash
124-# Basic start
125-gordon serve
126-
127-# With custom config
128-gordon serve --config /path/to/gordon.toml
129-gordon serve -c ./my-config.toml
130-
131-# With environment override
132-GORDON_SERVER_PORT=8080 gordon serve
133-GORDON_LOGGING_LEVEL=debug gordon serve
134-```
135-
136-### Signals
137-
138-Gordon responds to these signals:
139-
140-| Signal | Action |
141-|--------|--------|
142-| `SIGTERM` | Graceful shutdown |
143-| `SIGINT` | Graceful shutdown (Ctrl+C) |
144-| `SIGUSR1` | Reload configuration |
145-| `SIGUSR2` | Manual deploy (used by `gordon deploy`) |
146-
147-### Running with systemd
148-
149-```bash
150-# Create user service
151-mkdir -p ~/.config/systemd/user
152-cat > ~/.config/systemd/user/gordon.service <<EOF
153-[Unit]
154-Description=Gordon Container Platform
155-
156-[Service]
157-Type=simple
158-Restart=always
159-ExecStart=/usr/local/bin/gordon serve
160-
161-[Install]
162-WantedBy=default.target
163-EOF
164-
165-# Enable and start
166-systemctl --user daemon-reload
167-systemctl --user enable --now gordon
168-sudo loginctl enable-linger $USER
169-```
170-
171-### Startup Sequence
172-
173-1. Load configuration
174-2. Initialize logger
175-3. Create PID file
176-4. Connect to Docker/Podman runtime
177-5. Create storage directories
178-6. Initialize services (registry, proxy, auth)
179-7. Register event handlers
180-8. Start config file watcher
181-9. Sync existing containers
182-10. Start HTTP servers
183-
184-### Shutdown Sequence
185-
186-1. Receive shutdown signal
187-2. Stop accepting new requests
188-3. Complete in-flight requests
189-4. Stop managed containers (if configured)
190-5. Remove PID file
191-6. Exit
192-
193----
194-
195-## gordon reload
196-
197-Reload configuration and sync containers to match.
198-
199-### Synopsis
200-
201-```bash
202-gordon reload
203-```
204-
205-### Description
206-
207-Sends `SIGUSR1` to the running Gordon process, triggering:
208-
209-- Configuration file reload
210-- Route synchronization
211-- Deployment of containers for routes missing containers
212-- Attachment deployment
213-
214-### Example
215-
216-```bash
217-# After editing gordon.toml, apply changes without restart
218-vim ~/.config/gordon/gordon.toml
219-gordon reload
220-```
221-
222----
223-
224-## gordon deploy
225-
226-Manually deploy or redeploy a specific route.
227-
228-### Synopsis
229-
230-```bash
231-gordon deploy <domain> [options]
232-```
233-
234-### Arguments
235-
236-| Argument | Description |
237-|----------|-------------|
238-| `<domain>` | The domain name of the route to deploy (required) |
239-
240-### Options
241-
242-| Option | Description |
243-|--------|-------------|
244-| `--remote` | Remote Gordon URL |
245-| `--token` | Authentication token for remote |
246-
247-### Description
248-
249-**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
250-
251-**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
252-
253-Both modes trigger:
254-
255-- Fresh image pull (always pulls latest, ignoring cache)
256-- Container redeployment for the specified route
257-
258-### Examples
259-
260-```bash
261-# Local deployment
262-gordon deploy myapp.example.com
263-gordon deploy api.example.com
264-
265-# Remote deployment
266-gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
267-```
268-
269-### Use Cases
270-
271-- Recover from a failed deployment
272-- Force redeploy without pushing a new image
273-- Manual deployment when automatic deploy didn't trigger
274-- Trigger deployments on remote Gordon instances from CI/CD
275-
276----
277-
278-## gordon logs
279-
280-Display Gordon process logs or container logs.
281-
282-### Synopsis
283-
284-```bash
285-gordon logs [domain] [options]
286-```
287-
288-### Arguments
289-
290-| Argument | Description |
291-|----------|-------------|
292-| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
293-
294-### Options
295-
296-| Option | Short | Default | Description |
297-|--------|-------|---------|-------------|
298-| `--config` | `-c` | Auto | Path to config file |
299-| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
300-| `--lines` | `-n` | 50 | Number of lines to show |
301-| `--remote` | | | Remote Gordon URL |
302-| `--token` | | | Authentication token for remote |
303-
304-### Examples
305-
306-```bash
307-# Gordon process logs
308-gordon logs # Last 50 lines
309-gordon logs -f # Follow logs
310-gordon logs -n 100 # Last 100 lines
311-gordon logs -f -n 200 # Follow, starting from last 200 lines
312-
313-# Container logs
314-gordon logs myapp.local # Last 50 lines from container
315-gordon logs myapp.local -f # Follow container logs
316-gordon logs myapp.local -n 100 # Last 100 lines from container
317-
318-# Remote mode
319-gordon logs --remote https://gordon.mydomain.com --token $TOKEN
320-gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN
321-```
322-
323-### Log Locations
324-
325-```bash
326-# Using gordon logs
327-gordon logs -f
328-
329-# Direct file access
330-tail -f ~/.gordon/logs/gordon.log
331-
332-# With systemd
333-journalctl --user -u gordon -f
334-
335-# Container logs via docker (local alternative)
336-docker logs --tail 50 myapp.local
337-docker logs -f myapp.local
338-```
339-
340----
341-
342-## gordon version
343-
344-Print version information.
345-
346-### Synopsis
347-
348-```bash
349-gordon version
350-```
351-
352-### Output
353-
354-```
355-Gordon v2.0.0
356-Commit: abc1234
357-Build Date: 2024-01-15
358-```
359-
360----
361-
362-## gordon auth
363-
364-Manage registry authentication tokens and passwords.
365-
366-### Subcommands
367-
368-| Subcommand | Description |
369-|------------|-------------|
370-| `token generate` | Generate a new JWT token |
371-| `token list` | List all stored tokens |
372-| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
373-| `password hash` | Generate bcrypt password hash |
374-| `internal` | Show internal registry credentials |
375-
376-### gordon auth token generate
377-
378-Generate a new JWT authentication token for registry access.
379-
380-```bash
381-gordon auth token generate --subject <name> [options]
382-```
383-
384-**Options:**
385-
386-| Option | Default | Description |
387-|--------|---------|-------------|
388-| `--subject` | (required) | Username/subject for the token |
389-| `--scopes` | `push,pull` | Comma-separated scopes |
390-| `--expiry` | `30d` | Duration until expiry (0 = never) |
391-| `-c, --config` | Auto | Path to config file |
392-
393-**Duration format:**
394-
395-Supports human-friendly duration units:
396-
397-| Unit | Description | Example |
398-|------|-------------|---------|
399-| `d` | Days (24 hours) | `30d` |
400-| `w` | Weeks (7 days) | `2w` |
401-| `M` | Months (30 days) | `6M` |
402-| `y` | Years (365 days) | `1y` |
403-
404-Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
405-
406-Standard Go durations also work: `24h`, `30m`, `1h30m`
407-
408-**Examples:**
409-
410-```bash
411-# CI token that never expires
412-gordon auth token generate --subject github-actions --expiry 0
413-
414-# Read-only token for 30 days
415-gordon auth token generate --subject reader --scopes pull --expiry 30d
416-
417-# Push-only token for 1 year
418-gordon auth token generate --subject builder --scopes push --expiry 1y
419-
420-# Temporary token (24 hours)
421-gordon auth token generate --subject temp --expiry 24h
422-
423-# Token for 6 months
424-gordon auth token generate --subject deploy --expiry 6M
425-```
426-
427-**Output:**
428-
429-```
430-Token generated successfully!
431-Subject: github-actions
432-Scopes: push, pull
433-Expiry: never
434-
435-Token (use as password with docker login):
436-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
437-
438-Usage: docker login -u github-actions -p <token> <registry>
439-```
440-
441-### gordon auth token list
442-
443-List all stored authentication tokens.
444-
445-```bash
446-gordon auth token list [options]
447-```
448-
449-**Output:**
450-
451-```
452-ID Subject Expires Revoked
453-------------------------------------------------------------------------------------------
454-a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
455-b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
456-c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
457-```
458-
459-### gordon auth token revoke
460-
461-Revoke a token by its ID.
462-
463-```bash
464-gordon auth token revoke <token-id> [options]
465-```
466-
467-**Example:**
468-
469-```bash
470-gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
471-```
472-
473-**Output:**
474-
475-```
476-Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
477-```
478-
479-### gordon auth password hash
480-
481-Generate a bcrypt hash for password authentication.
482-
483-```bash
484-gordon auth password hash
485-```
486-
487-Interactively prompts for a password and outputs the bcrypt hash.
488-
489-**Output:**
490-
491-```
492-Enter password: ********
493-
494-Bcrypt hash (store in your secrets backend):
495-$2a$10$N9qo8uLOickgx2ZMRZoMye...
496-
497-Then reference the path in your config:
498- [auth]
499- type = "password"
500- password_hash = "gordon/auth/password_hash"
501-```
502-
503-### gordon auth internal
504-
505-Display the auto-generated internal registry credentials.
506-
507-```bash
508-gordon auth internal
509-```
510-
511-Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
512-
513-**Output:**
514-
515-```
516-Internal Registry Credentials
517-==============================
518-Username: gordon-internal
519-Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
520-
521-Usage:
522- docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
523-```
524-
525-**Notes:**
526-- Credentials are regenerated each time Gordon starts
527-- Only available while Gordon is running
528-- Used for manual `docker pull` from the local registry during debugging
529-
530-**Use cases:**
531-- Debugging image pull failures
532-- Manual recovery after deployment issues
533-- Inspecting images in the local registry
534-
535----
536-
537-## Token Scopes
538-
539-| Scope | Permission |
540-|-------|------------|
541-| `push` | Push images to registry |
542-| `pull` | Pull images from registry |
543-| `push,pull` | Both push and pull (default) |
544-
545-## Token Expiry Formats
546-
547-| Format | Duration |
548-|--------|----------|
549-| `0` | Never expires |
550-| `24h` | 24 hours |
551-| `720h` | 30 days |
552-| `8760h` | 1 year |
553-
554----
555-
556-## Workflow Examples
557-
558-### CI/CD Setup
559-
560-```bash
561-# Generate token for CI
562-gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
563-
564-# Save token as CI secret
565-# GitHub: Settings → Secrets → New repository secret
566-# GitLab: Settings → CI/CD → Variables
567-```
568-
569-### Docker Login
570-
571-```bash
572-# Using generated token
573-docker login -u ci-bot -p <token> registry.mydomain.com
574-
575-# In CI/CD
576-echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
577-```
578-
579-### Token Rotation
580-
581-```bash
582-# Generate new token
583-gordon auth token generate --subject ci-bot --expiry 0
584-
585-# Update CI secrets with new token
586-
587-# Revoke old token
588-gordon auth token revoke <old-token-id>
589-```
590-
591-### Password Setup
592-
593-```bash
594-# Generate hash
595-gordon auth password hash
596-# Enter: mypassword
597-
598-# Store in pass
599-pass insert gordon/auth/password_hash
600-# Paste: $2a$10$...
601-
602-# Configure gordon.toml
603-[auth]
604-enabled = true
605-type = "password"
606-secrets_backend = "pass"
607-username = "deploy"
608-password_hash = "gordon/auth/password_hash"
609-```
610-
611----
612-
613-## gordon routes
614-
615-Manage routes on local or remote Gordon instances.
616-
617-### Subcommands
618-
619-| Subcommand | Description |
620-|------------|-------------|
621-| `list` | List all routes |
622-| `add` | Add a new route |
623-| `remove` | Remove a route |
624-| `deploy` | Deploy a specific route |
625-
626-### gordon routes list
627-
628-List all configured routes.
629-
630-```bash
631-gordon routes list
632-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
633-```
634-
635-### gordon routes add
636-
637-Add a new route.
638-
639-```bash
640-gordon routes add <domain> <image>
641-gordon routes add myapp.example.com myapp:latest
642-```
643-
644-### gordon routes remove
645-
646-Remove a route.
647-
648-```bash
649-gordon routes remove <domain>
650-gordon routes remove myapp.example.com
651-```
652-
653-### gordon routes deploy
654-
655-Deploy or redeploy a specific route.
656-
657-```bash
658-gordon routes deploy <domain>
659-gordon routes deploy myapp.example.com
660-```
661-
662----
663-
664-## gordon attachments
665-
666-Manage attachments on local or remote Gordon instances.
667-
668-### Subcommands
669-
670-| Subcommand | Description |
671-|------------|-------------|
672-| `list` | List all attachments or attachments for a specific target |
673-| `add` | Add an attachment to a domain or network group |
674-| `remove` | Remove an attachment from a domain or network group |
675-
676-### gordon attachments list
677-
678-List all configured attachments.
679-
680-```bash
681-# List all attachments
682-gordon attachments list
683-
684-# List attachments for a specific domain or group
685-gordon attachments list app.example.com
686-gordon attachments list backend
687-
688-# Remote mode
689-gordon attachments list --remote https://gordon.mydomain.com --token $TOKEN
690-```
691-
692-### gordon attachments add
693-
694-Add an attachment to a domain or network group.
695-
696-```bash
697-gordon attachments add <domain-or-group> <image>
698-gordon attachments add app.example.com postgres:15
699-gordon attachments add backend redis:7-alpine
700-```
701-
702-### gordon attachments remove
703-
704-Remove an attachment.
705-
706-```bash
707-gordon attachments remove <domain-or-group> <image>
708-gordon attachments remove app.example.com postgres:15
709-```
710-
711-### Alias
712-
713-`gordon attach` is an alias for `gordon attachments`:
714-
715-```bash
716-gordon attach list
717-gordon attach add app.example.com postgres:15
718-gordon attach remove app.example.com postgres:15
719-```
720-
721----
722-
723-## gordon secrets
724-
725-Manage secrets on local or remote Gordon instances.
726-
727-### Subcommands
728-
729-| Subcommand | Description |
730-|------------|-------------|
731-| `list` | List all secrets for a domain |
732-| `set` | Set a secret value |
733-| `remove` | Remove a secret |
734-
735-### Examples
736-
737-```bash
738-# Local mode (reads/writes secrets directly)
739-gordon secrets list myapp.local
740-gordon secrets set myapp.local DATABASE_URL "postgres://..."
741-gordon secrets remove myapp.local DATABASE_URL
742-
743-# Remote mode
744-gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
745-gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote ... --token ...
746-gordon secrets remove myapp.local DATABASE_URL --remote ... --token ...
747-```
748-
749----
750-
751-## gordon remotes
752-
753-Manage saved remote Gordon instances for easier CLI usage.
754-
755-### Subcommands
756-
757-| Subcommand | Description |
758-|------------|-------------|
759-| `list` | List saved remotes |
760-| `add` | Add a new remote |
761-| `remove` | Remove a saved remote |
762-| `use` | Set active remote |
763-
764-### Examples
765-
766-```bash
767-# Add a remote
768-gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
769-
770-# List saved remotes
771-gordon remotes list
772-
773-# Set active remote
774-gordon remotes use prod
775-
776-# Now use without --remote flag
777-gordon routes list
778-```
779-
780----
781-
782-## Exit Codes
783-
784-| Code | Meaning |
785-|------|---------|
786-| 0 | Success |
787-| 1 | General error |
788-| 2 | Configuration error |
789-
790-## Environment Variables
791-
792-Gordon reads configuration from environment variables:
793-
794-```bash
795-GORDON_SERVER_PORT=8080 gordon serve
796-GORDON_LOGGING_LEVEL=debug gordon serve
797-```
798-
799-Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
800-
801-## Related
802-
803-- [Core Concepts](../concepts.md)
804-- [Configuration Reference](../config/index.md)
A docs/cli/index.md +118 -0
@@ -0,0 +1,118 @@
1+# CLI Commands
2+
3+Gordon provides a command-line interface for server management, deployment, and authentication.
4+
5+## Commands Overview
6+
7+| Command | Description | Documentation |
8+|---------|-------------|---------------|
9+| `gordon serve` | Start the Gordon server | [serve](./serve.md) |
10+| `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) |
11+| `gordon deploy` | Manually deploy or redeploy a specific route | [serve](./serve.md#gordon-deploy) |
12+| `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
13+| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
14+| `gordon auth` | Manage registry authentication | [auth](./auth.md) |
15+| `gordon routes` | Manage routes (local or remote) | [routes](./routes.md) |
16+| `gordon attachments` | Manage attachments (local or remote) | [attachments](./attachments.md) |
17+| `gordon secrets` | Manage secrets (local or remote) | [secrets](./secrets.md) |
18+| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
19+
20+## Quick Reference
21+
22+```bash
23+# Start Gordon
24+gordon serve
25+gordon serve --config /path/to/config.toml
26+
27+# Reload configuration
28+gordon reload
29+
30+# Deploy a specific route
31+gordon deploy myapp.example.com
32+
33+# View logs
34+gordon logs # Gordon process logs
35+gordon logs -f # Follow process logs
36+gordon logs -n 100 # Last 100 lines
37+gordon logs myapp.local # Container logs for myapp.local
38+gordon logs myapp.local -f # Follow container logs
39+
40+# Check version
41+gordon version
42+
43+# Authentication
44+gordon auth token generate --subject ci-bot --expiry 0
45+gordon auth token list
46+gordon auth token revoke <token-id>
47+gordon auth password hash
48+gordon auth internal
49+
50+# Routes
51+gordon routes list
52+gordon routes add myapp.example.com myapp:latest
53+gordon routes remove myapp.example.com
54+gordon routes deploy myapp.example.com
55+
56+# Attachments
57+gordon attachments list
58+gordon attachments add app.example.com postgres:15
59+gordon attachments remove app.example.com postgres:15
60+
61+# Secrets
62+gordon secrets list myapp.local
63+gordon secrets set myapp.local DATABASE_URL "postgres://..."
64+gordon secrets remove myapp.local DATABASE_URL
65+
66+# Remotes
67+gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
68+gordon remotes list
69+gordon remotes use prod
70+```
71+
72+## Global Options
73+
74+| Option | Description |
75+|--------|-------------|
76+| `-c, --config` | Path to configuration file |
77+| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
78+| `--token` | Authentication token for remote |
79+
80+### Remote Targeting
81+
82+The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
83+
84+**Important:** The remote URL must be the `gordon_domain` configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.
85+
86+```bash
87+# Using flags (use the gordon_domain from remote Gordon config)
88+gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
89+
90+# Using environment variables
91+export GORDON_REMOTE=https://gordon.mydomain.com
92+export GORDON_TOKEN=$TOKEN
93+gordon routes list
94+```
95+
96+## Exit Codes
97+
98+| Code | Meaning |
99+|------|---------|
100+| 0 | Success |
101+| 1 | General error |
102+| 2 | Configuration error |
103+
104+## Environment Variables
105+
106+Gordon reads configuration from environment variables:
107+
108+```bash
109+GORDON_SERVER_PORT=8080 gordon serve
110+GORDON_LOGGING_LEVEL=debug gordon serve
111+```
112+
113+Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
114+
115+## Related
116+
117+- [Core Concepts](../concepts.md)
118+- [Configuration Reference](../config/index.md)
@@ -0,0 +1,118 @@
1+# CLI Commands
2+
3+Gordon provides a command-line interface for server management, deployment, and authentication.
4+
5+## Commands Overview
6+
7+| Command | Description | Documentation |
8+|---------|-------------|---------------|
9+| `gordon serve` | Start the Gordon server | [serve](./serve.md) |
10+| `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) |
11+| `gordon deploy` | Manually deploy or redeploy a specific route | [serve](./serve.md#gordon-deploy) |
12+| `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
13+| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
14+| `gordon auth` | Manage registry authentication | [auth](./auth.md) |
15+| `gordon routes` | Manage routes (local or remote) | [routes](./routes.md) |
16+| `gordon attachments` | Manage attachments (local or remote) | [attachments](./attachments.md) |
17+| `gordon secrets` | Manage secrets (local or remote) | [secrets](./secrets.md) |
18+| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
19+
20+## Quick Reference
21+
22+```bash
23+# Start Gordon
24+gordon serve
25+gordon serve --config /path/to/config.toml
26+
27+# Reload configuration
28+gordon reload
29+
30+# Deploy a specific route
31+gordon deploy myapp.example.com
32+
33+# View logs
34+gordon logs # Gordon process logs
35+gordon logs -f # Follow process logs
36+gordon logs -n 100 # Last 100 lines
37+gordon logs myapp.local # Container logs for myapp.local
38+gordon logs myapp.local -f # Follow container logs
39+
40+# Check version
41+gordon version
42+
43+# Authentication
44+gordon auth token generate --subject ci-bot --expiry 0
45+gordon auth token list
46+gordon auth token revoke <token-id>
47+gordon auth password hash
48+gordon auth internal
49+
50+# Routes
51+gordon routes list
52+gordon routes add myapp.example.com myapp:latest
53+gordon routes remove myapp.example.com
54+gordon routes deploy myapp.example.com
55+
56+# Attachments
57+gordon attachments list
58+gordon attachments add app.example.com postgres:15
59+gordon attachments remove app.example.com postgres:15
60+
61+# Secrets
62+gordon secrets list myapp.local
63+gordon secrets set myapp.local DATABASE_URL "postgres://..."
64+gordon secrets remove myapp.local DATABASE_URL
65+
66+# Remotes
67+gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
68+gordon remotes list
69+gordon remotes use prod
70+```
71+
72+## Global Options
73+
74+| Option | Description |
75+|--------|-------------|
76+| `-c, --config` | Path to configuration file |
77+| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
78+| `--token` | Authentication token for remote |
79+
80+### Remote Targeting
81+
82+The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
83+
84+**Important:** The remote URL must be the `gordon_domain` configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.
85+
86+```bash
87+# Using flags (use the gordon_domain from remote Gordon config)
88+gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
89+
90+# Using environment variables
91+export GORDON_REMOTE=https://gordon.mydomain.com
92+export GORDON_TOKEN=$TOKEN
93+gordon routes list
94+```
95+
96+## Exit Codes
97+
98+| Code | Meaning |
99+|------|---------|
100+| 0 | Success |
101+| 1 | General error |
102+| 2 | Configuration error |
103+
104+## Environment Variables
105+
106+Gordon reads configuration from environment variables:
107+
108+```bash
109+GORDON_SERVER_PORT=8080 gordon serve
110+GORDON_LOGGING_LEVEL=debug gordon serve
111+```
112+
113+Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
114+
115+## Related
116+
117+- [Core Concepts](../concepts.md)
118+- [Configuration Reference](../config/index.md)
A docs/cli/remotes.md +256 -0
@@ -0,0 +1,256 @@
1+# Remotes Commands
2+
3+Manage saved remote Gordon instances for easier CLI usage.
4+
5+## gordon remotes
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List saved remotes |
12+| `add` | Add a new remote |
13+| `remove` | Remove a saved remote |
14+| `use` | Set active remote |
15+
16+---
17+
18+## gordon remotes list
19+
20+List all saved remotes.
21+
22+```bash
23+gordon remotes list
24+```
25+
26+### Output
27+
28+```
29+Saved Remotes
30+
31+Name URL Token Status
32+-------------------------------------------------------------------------------
33+prod https://gordon.mydomain.com $PROD_TOKEN active
34+staging https://staging.mydomain.com set
35+dev https://dev.mydomain.com none
36+```
37+
38+---
39+
40+## gordon remotes add
41+
42+Add a new remote.
43+
44+```bash
45+gordon remotes add <name> <url> [options]
46+```
47+
48+### Arguments
49+
50+| Argument | Description |
51+|----------|-------------|
52+| `<name>` | Name for the remote (e.g., `prod`, `staging`) |
53+| `<url>` | Gordon URL (the `gordon_domain` from remote config) |
54+
55+### Options
56+
57+| Option | Description |
58+|--------|-------------|
59+| `--token` | Store token directly in config |
60+| `--token-env` | Store environment variable name (token resolved at runtime) |
61+
62+### Examples
63+
64+```bash
65+# Basic (no token)
66+gordon remotes add prod https://gordon.mydomain.com
67+
68+# With direct token
69+gordon remotes add prod https://gordon.mydomain.com --token eyJ...
70+
71+# With environment variable reference (recommended)
72+gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
73+```
74+
75+### Token Security
76+
77+**Option 1: Environment Variable Reference (Recommended)**
78+
79+```bash
80+gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
81+```
82+
83+The `remotes.toml` stores only the variable name:
84+
85+```toml
86+[remotes.prod]
87+url = "https://gordon.mydomain.com"
88+token_env = "PROD_TOKEN"
89+```
90+
91+At runtime, Gordon reads `$PROD_TOKEN` from the environment.
92+
93+**Option 2: Direct Token Storage**
94+
95+```bash
96+gordon remotes add prod https://gordon.mydomain.com --token eyJ...
97+```
98+
99+The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
100+
101+```bash
102+chmod 600 ~/.config/gordon/remotes.toml
103+```
104+
105+---
106+
107+## gordon remotes remove
108+
109+Remove a saved remote.
110+
111+```bash
112+gordon remotes remove <name>
113+gordon remotes remove <name> --force # Skip confirmation
114+```
115+
116+### Arguments
117+
118+| Argument | Description |
119+|----------|-------------|
120+| `<name>` | Name of the remote to remove |
121+
122+### Options
123+
124+| Option | Description |
125+|--------|-------------|
126+| `--force` | Skip confirmation prompt |
127+
128+### Example
129+
130+```bash
131+gordon remotes remove staging
132+```
133+
134+---
135+
136+## gordon remotes use
137+
138+Set the active remote.
139+
140+```bash
141+gordon remotes use <name>
142+```
143+
144+### Arguments
145+
146+| Argument | Description |
147+|----------|-------------|
148+| `<name>` | Name of the remote to set as active |
149+
150+### Description
151+
152+When a remote is active, it's used automatically for all remote-capable commands without needing to specify `--remote` and `--token`:
153+
154+```bash
155+gordon remotes use prod
156+gordon routes list # Uses prod remote automatically
157+gordon secrets list app.com # Uses prod remote automatically
158+```
159+
160+### Example
161+
162+```bash
163+gordon remotes use prod
164+```
165+
166+---
167+
168+## Configuration File
169+
170+Remotes are stored in `~/.config/gordon/remotes.toml`:
171+
172+```toml
173+active = "prod"
174+
175+[remotes.prod]
176+url = "https://gordon.mydomain.com"
177+token_env = "PROD_TOKEN"
178+
179+[remotes.staging]
180+url = "https://staging.mydomain.com"
181+token = "eyJ..."
182+```
183+
184+## Resolution Precedence
185+
186+When multiple sources specify remote or token, the CLI uses this priority:
187+
188+**Remote URL:**
189+1. `--remote` flag
190+2. `GORDON_REMOTE` environment variable
191+3. Active remote from `remotes.toml`
192+
193+**Token:**
194+1. `--token` flag
195+2. `GORDON_TOKEN` environment variable
196+3. Token from active remote in `remotes.toml`
197+
198+This allows overriding specific values while keeping defaults:
199+
200+```bash
201+# Active remote is prod, but use different token
202+gordon routes list --token $TEMPORARY_TOKEN
203+```
204+
205+---
206+
207+## Workflow Examples
208+
209+### Multi-Environment Setup
210+
211+```bash
212+# Add all environments
213+gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
214+gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
215+gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
216+
217+# Work with prod
218+gordon remotes use prod
219+gordon routes list
220+gordon secrets list myapp.example.com
221+
222+# Switch to staging
223+gordon remotes use staging
224+gordon routes list
225+```
226+
227+### CI/CD Pipeline
228+
229+```yaml
230+# GitHub Actions example
231+env:
232+ GORDON_REMOTE: ${{ secrets.GORDON_URL }}
233+ GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
234+
235+steps:
236+ - name: Deploy to Gordon
237+ run: |
238+ gordon routes deploy myapp.example.com
239+```
240+
241+### Compare Environments
242+
243+```bash
244+# Compare routes across environments
245+gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
246+gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
247+
248+# Or switch between active remotes
249+gordon remotes use prod && gordon routes list
250+gordon remotes use staging && gordon routes list
251+```
252+
253+## Related
254+
255+- [CLI Overview](./index.md)
256+- [Remote CLI Guide](/wiki/guides/remote-cli.md)
@@ -0,0 +1,256 @@
1+# Remotes Commands
2+
3+Manage saved remote Gordon instances for easier CLI usage.
4+
5+## gordon remotes
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List saved remotes |
12+| `add` | Add a new remote |
13+| `remove` | Remove a saved remote |
14+| `use` | Set active remote |
15+
16+---
17+
18+## gordon remotes list
19+
20+List all saved remotes.
21+
22+```bash
23+gordon remotes list
24+```
25+
26+### Output
27+
28+```
29+Saved Remotes
30+
31+Name URL Token Status
32+-------------------------------------------------------------------------------
33+prod https://gordon.mydomain.com $PROD_TOKEN active
34+staging https://staging.mydomain.com set
35+dev https://dev.mydomain.com none
36+```
37+
38+---
39+
40+## gordon remotes add
41+
42+Add a new remote.
43+
44+```bash
45+gordon remotes add <name> <url> [options]
46+```
47+
48+### Arguments
49+
50+| Argument | Description |
51+|----------|-------------|
52+| `<name>` | Name for the remote (e.g., `prod`, `staging`) |
53+| `<url>` | Gordon URL (the `gordon_domain` from remote config) |
54+
55+### Options
56+
57+| Option | Description |
58+|--------|-------------|
59+| `--token` | Store token directly in config |
60+| `--token-env` | Store environment variable name (token resolved at runtime) |
61+
62+### Examples
63+
64+```bash
65+# Basic (no token)
66+gordon remotes add prod https://gordon.mydomain.com
67+
68+# With direct token
69+gordon remotes add prod https://gordon.mydomain.com --token eyJ...
70+
71+# With environment variable reference (recommended)
72+gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
73+```
74+
75+### Token Security
76+
77+**Option 1: Environment Variable Reference (Recommended)**
78+
79+```bash
80+gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
81+```
82+
83+The `remotes.toml` stores only the variable name:
84+
85+```toml
86+[remotes.prod]
87+url = "https://gordon.mydomain.com"
88+token_env = "PROD_TOKEN"
89+```
90+
91+At runtime, Gordon reads `$PROD_TOKEN` from the environment.
92+
93+**Option 2: Direct Token Storage**
94+
95+```bash
96+gordon remotes add prod https://gordon.mydomain.com --token eyJ...
97+```
98+
99+The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
100+
101+```bash
102+chmod 600 ~/.config/gordon/remotes.toml
103+```
104+
105+---
106+
107+## gordon remotes remove
108+
109+Remove a saved remote.
110+
111+```bash
112+gordon remotes remove <name>
113+gordon remotes remove <name> --force # Skip confirmation
114+```
115+
116+### Arguments
117+
118+| Argument | Description |
119+|----------|-------------|
120+| `<name>` | Name of the remote to remove |
121+
122+### Options
123+
124+| Option | Description |
125+|--------|-------------|
126+| `--force` | Skip confirmation prompt |
127+
128+### Example
129+
130+```bash
131+gordon remotes remove staging
132+```
133+
134+---
135+
136+## gordon remotes use
137+
138+Set the active remote.
139+
140+```bash
141+gordon remotes use <name>
142+```
143+
144+### Arguments
145+
146+| Argument | Description |
147+|----------|-------------|
148+| `<name>` | Name of the remote to set as active |
149+
150+### Description
151+
152+When a remote is active, it's used automatically for all remote-capable commands without needing to specify `--remote` and `--token`:
153+
154+```bash
155+gordon remotes use prod
156+gordon routes list # Uses prod remote automatically
157+gordon secrets list app.com # Uses prod remote automatically
158+```
159+
160+### Example
161+
162+```bash
163+gordon remotes use prod
164+```
165+
166+---
167+
168+## Configuration File
169+
170+Remotes are stored in `~/.config/gordon/remotes.toml`:
171+
172+```toml
173+active = "prod"
174+
175+[remotes.prod]
176+url = "https://gordon.mydomain.com"
177+token_env = "PROD_TOKEN"
178+
179+[remotes.staging]
180+url = "https://staging.mydomain.com"
181+token = "eyJ..."
182+```
183+
184+## Resolution Precedence
185+
186+When multiple sources specify remote or token, the CLI uses this priority:
187+
188+**Remote URL:**
189+1. `--remote` flag
190+2. `GORDON_REMOTE` environment variable
191+3. Active remote from `remotes.toml`
192+
193+**Token:**
194+1. `--token` flag
195+2. `GORDON_TOKEN` environment variable
196+3. Token from active remote in `remotes.toml`
197+
198+This allows overriding specific values while keeping defaults:
199+
200+```bash
201+# Active remote is prod, but use different token
202+gordon routes list --token $TEMPORARY_TOKEN
203+```
204+
205+---
206+
207+## Workflow Examples
208+
209+### Multi-Environment Setup
210+
211+```bash
212+# Add all environments
213+gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
214+gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
215+gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
216+
217+# Work with prod
218+gordon remotes use prod
219+gordon routes list
220+gordon secrets list myapp.example.com
221+
222+# Switch to staging
223+gordon remotes use staging
224+gordon routes list
225+```
226+
227+### CI/CD Pipeline
228+
229+```yaml
230+# GitHub Actions example
231+env:
232+ GORDON_REMOTE: ${{ secrets.GORDON_URL }}
233+ GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
234+
235+steps:
236+ - name: Deploy to Gordon
237+ run: |
238+ gordon routes deploy myapp.example.com
239+```
240+
241+### Compare Environments
242+
243+```bash
244+# Compare routes across environments
245+gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
246+gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
247+
248+# Or switch between active remotes
249+gordon remotes use prod && gordon routes list
250+gordon remotes use staging && gordon routes list
251+```
252+
253+## Related
254+
255+- [CLI Overview](./index.md)
256+- [Remote CLI Guide](/wiki/guides/remote-cli.md)
A docs/cli/routes.md +148 -0
@@ -0,0 +1,148 @@
1+# Routes Commands
2+
3+Manage routes on local or remote Gordon instances.
4+
5+## gordon routes
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all routes |
12+| `add` | Add a new route |
13+| `remove` | Remove a route |
14+| `deploy` | Deploy a specific route |
15+
16+---
17+
18+## gordon routes list
19+
20+List all configured routes.
21+
22+```bash
23+gordon routes list
24+gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
25+```
26+
27+### Output
28+
29+```
30+Domain Image Status
31+--------------------------------------------------------------------------------
32+app.example.com myapp:latest running
33+api.example.com myapi:v2.1.0 running
34+admin.example.com admin-panel:latest stopped
35+```
36+
37+---
38+
39+## gordon routes add
40+
41+Add a new route.
42+
43+```bash
44+gordon routes add <domain> <image>
45+gordon routes add myapp.example.com myapp:latest
46+```
47+
48+### Arguments
49+
50+| Argument | Description |
51+|----------|-------------|
52+| `<domain>` | The domain name for the route |
53+| `<image>` | The container image to deploy |
54+
55+### Options
56+
57+| Option | Description |
58+|--------|-------------|
59+| `--remote` | Remote Gordon URL |
60+| `--token` | Authentication token for remote |
61+
62+### Examples
63+
64+```bash
65+# Local
66+gordon routes add myapp.example.com myapp:latest
67+gordon routes add api.example.com myapi:v2.1.0
68+
69+# Remote
70+gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
71+```
72+
73+---
74+
75+## gordon routes remove
76+
77+Remove a route.
78+
79+```bash
80+gordon routes remove <domain>
81+gordon routes remove myapp.example.com
82+```
83+
84+### Arguments
85+
86+| Argument | Description |
87+|----------|-------------|
88+| `<domain>` | The domain name of the route to remove |
89+
90+### Options
91+
92+| Option | Description |
93+|--------|-------------|
94+| `--remote` | Remote Gordon URL |
95+| `--token` | Authentication token for remote |
96+
97+### Examples
98+
99+```bash
100+# Local
101+gordon routes remove myapp.example.com
102+
103+# Remote
104+gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
105+```
106+
107+---
108+
109+## gordon routes deploy
110+
111+Deploy or redeploy a specific route.
112+
113+```bash
114+gordon routes deploy <domain>
115+gordon routes deploy myapp.example.com
116+```
117+
118+### Arguments
119+
120+| Argument | Description |
121+|----------|-------------|
122+| `<domain>` | The domain name of the route to deploy |
123+
124+### Options
125+
126+| Option | Description |
127+|--------|-------------|
128+| `--remote` | Remote Gordon URL |
129+| `--token` | Authentication token for remote |
130+
131+### Description
132+
133+Triggers a fresh image pull and container redeployment for the specified route.
134+
135+### Examples
136+
137+```bash
138+# Local
139+gordon routes deploy myapp.example.com
140+
141+# Remote
142+gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
143+```
144+
145+## Related
146+
147+- [CLI Overview](./index.md)
148+- [Routes Configuration](../config/routes.md)
@@ -0,0 +1,148 @@
1+# Routes Commands
2+
3+Manage routes on local or remote Gordon instances.
4+
5+## gordon routes
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all routes |
12+| `add` | Add a new route |
13+| `remove` | Remove a route |
14+| `deploy` | Deploy a specific route |
15+
16+---
17+
18+## gordon routes list
19+
20+List all configured routes.
21+
22+```bash
23+gordon routes list
24+gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
25+```
26+
27+### Output
28+
29+```
30+Domain Image Status
31+--------------------------------------------------------------------------------
32+app.example.com myapp:latest running
33+api.example.com myapi:v2.1.0 running
34+admin.example.com admin-panel:latest stopped
35+```
36+
37+---
38+
39+## gordon routes add
40+
41+Add a new route.
42+
43+```bash
44+gordon routes add <domain> <image>
45+gordon routes add myapp.example.com myapp:latest
46+```
47+
48+### Arguments
49+
50+| Argument | Description |
51+|----------|-------------|
52+| `<domain>` | The domain name for the route |
53+| `<image>` | The container image to deploy |
54+
55+### Options
56+
57+| Option | Description |
58+|--------|-------------|
59+| `--remote` | Remote Gordon URL |
60+| `--token` | Authentication token for remote |
61+
62+### Examples
63+
64+```bash
65+# Local
66+gordon routes add myapp.example.com myapp:latest
67+gordon routes add api.example.com myapi:v2.1.0
68+
69+# Remote
70+gordon routes add myapp.example.com myapp:latest --remote https://gordon.mydomain.com --token $TOKEN
71+```
72+
73+---
74+
75+## gordon routes remove
76+
77+Remove a route.
78+
79+```bash
80+gordon routes remove <domain>
81+gordon routes remove myapp.example.com
82+```
83+
84+### Arguments
85+
86+| Argument | Description |
87+|----------|-------------|
88+| `<domain>` | The domain name of the route to remove |
89+
90+### Options
91+
92+| Option | Description |
93+|--------|-------------|
94+| `--remote` | Remote Gordon URL |
95+| `--token` | Authentication token for remote |
96+
97+### Examples
98+
99+```bash
100+# Local
101+gordon routes remove myapp.example.com
102+
103+# Remote
104+gordon routes remove myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
105+```
106+
107+---
108+
109+## gordon routes deploy
110+
111+Deploy or redeploy a specific route.
112+
113+```bash
114+gordon routes deploy <domain>
115+gordon routes deploy myapp.example.com
116+```
117+
118+### Arguments
119+
120+| Argument | Description |
121+|----------|-------------|
122+| `<domain>` | The domain name of the route to deploy |
123+
124+### Options
125+
126+| Option | Description |
127+|--------|-------------|
128+| `--remote` | Remote Gordon URL |
129+| `--token` | Authentication token for remote |
130+
131+### Description
132+
133+Triggers a fresh image pull and container redeployment for the specified route.
134+
135+### Examples
136+
137+```bash
138+# Local
139+gordon routes deploy myapp.example.com
140+
141+# Remote
142+gordon routes deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
143+```
144+
145+## Related
146+
147+- [CLI Overview](./index.md)
148+- [Routes Configuration](../config/routes.md)
A docs/cli/secrets.md +182 -0
@@ -0,0 +1,182 @@
1+# Secrets Commands
2+
3+Manage secrets on local or remote Gordon instances.
4+
5+## gordon secrets
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all secrets for a domain |
12+| `set` | Set a secret value |
13+| `remove` | Remove a secret |
14+
15+---
16+
17+## gordon secrets list
18+
19+List all secrets for a specific domain.
20+
21+```bash
22+gordon secrets list <domain>
23+```
24+
25+### Arguments
26+
27+| Argument | Description |
28+|----------|-------------|
29+| `<domain>` | The domain name to list secrets for |
30+
31+### Options
32+
33+| Option | Description |
34+|--------|-------------|
35+| `--remote` | Remote Gordon URL |
36+| `--token` | Authentication token for remote |
37+
38+### Examples
39+
40+```bash
41+# Local
42+gordon secrets list myapp.local
43+
44+# Remote
45+gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
46+```
47+
48+### Output
49+
50+```
51+Secret Value (masked)
52+--------------------------------------------------------------------------------
53+DATABASE_URL postgres://...
54+API_KEY ****
55+JWT_SECRET ****
56+```
57+
58+---
59+
60+## gordon secrets set
61+
62+Set a secret value for a domain.
63+
64+```bash
65+gordon secrets set <domain> <key> <value>
66+gordon secrets set myapp.local DATABASE_URL "postgres://..."
67+```
68+
69+### Arguments
70+
71+| Argument | Description |
72+|----------|-------------|
73+| `<domain>` | The domain name to set the secret for |
74+| `<key>` | The secret key (environment variable name) |
75+| `<value>` | The secret value |
76+
77+### Options
78+
79+| Option | Description |
80+|--------|-------------|
81+| `--remote` | Remote Gordon URL |
82+| `--token` | Authentication token for remote |
83+
84+### Examples
85+
86+```bash
87+# Local
88+gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/db"
89+gordon secrets set myapp.local API_KEY "your-api-key"
90+
91+# Remote
92+gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote https://gordon.mydomain.com --token $TOKEN
93+```
94+
95+---
96+
97+## gordon secrets remove
98+
99+Remove a secret from a domain.
100+
101+```bash
102+gordon secrets remove <domain> <key>
103+```
104+
105+### Arguments
106+
107+| Argument | Description |
108+|----------|-------------|
109+| `<domain>` | The domain name |
110+| `<key>` | The secret key to remove |
111+
112+### Options
113+
114+| Option | Description |
115+|--------|-------------|
116+| `--remote` | Remote Gordon URL |
117+| `--token` | Authentication token for remote |
118+
119+### Examples
120+
121+```bash
122+# Local
123+gordon secrets remove myapp.local DATABASE_URL
124+
125+# Remote
126+gordon secrets remove myapp.local DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
127+```
128+
129+---
130+
131+## Workflow Examples
132+
133+### Setting Up Application Secrets
134+
135+```bash
136+# Database connection
137+gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/mydb"
138+
139+# API keys
140+gordon secrets set myapp.local STRIPE_KEY "sk_live_..."
141+gordon secrets set myapp.local SENDGRID_KEY "SG..."
142+
143+# JWT secret
144+gordon secrets set myapp.local JWT_SECRET "your-jwt-secret-here"
145+
146+# Verify
147+gordon secrets list myapp.local
148+```
149+
150+### CI/CD Secret Management
151+
152+```bash
153+# In your CI/CD pipeline
154+export GORDON_REMOTE=https://gordon.mydomain.com
155+export GORDON_TOKEN=$GORDON_TOKEN
156+
157+# Update secrets before deploy
158+gordon secrets set myapp.example.com DATABASE_URL "$DATABASE_URL"
159+gordon secrets set myapp.example.com API_KEY "$API_KEY"
160+
161+# Deploy
162+gordon routes deploy myapp.example.com
163+```
164+
165+### Rotating Secrets
166+
167+```bash
168+# Generate new secret
169+NEW_JWT_SECRET=$(openssl rand -base64 32)
170+
171+# Update the secret
172+gordon secrets set myapp.local JWT_SECRET "$NEW_JWT_SECRET"
173+
174+# Redeploy to pick up new secret
175+gordon routes deploy myapp.local
176+```
177+
178+## Related
179+
180+- [CLI Overview](./index.md)
181+- [Secrets Configuration](../config/secrets.md)
182+- [Environment Variables](../config/env.md)
@@ -0,0 +1,182 @@
1+# Secrets Commands
2+
3+Manage secrets on local or remote Gordon instances.
4+
5+## gordon secrets
6+
7+### Subcommands
8+
9+| Subcommand | Description |
10+|------------|-------------|
11+| `list` | List all secrets for a domain |
12+| `set` | Set a secret value |
13+| `remove` | Remove a secret |
14+
15+---
16+
17+## gordon secrets list
18+
19+List all secrets for a specific domain.
20+
21+```bash
22+gordon secrets list <domain>
23+```
24+
25+### Arguments
26+
27+| Argument | Description |
28+|----------|-------------|
29+| `<domain>` | The domain name to list secrets for |
30+
31+### Options
32+
33+| Option | Description |
34+|--------|-------------|
35+| `--remote` | Remote Gordon URL |
36+| `--token` | Authentication token for remote |
37+
38+### Examples
39+
40+```bash
41+# Local
42+gordon secrets list myapp.local
43+
44+# Remote
45+gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
46+```
47+
48+### Output
49+
50+```
51+Secret Value (masked)
52+--------------------------------------------------------------------------------
53+DATABASE_URL postgres://...
54+API_KEY ****
55+JWT_SECRET ****
56+```
57+
58+---
59+
60+## gordon secrets set
61+
62+Set a secret value for a domain.
63+
64+```bash
65+gordon secrets set <domain> <key> <value>
66+gordon secrets set myapp.local DATABASE_URL "postgres://..."
67+```
68+
69+### Arguments
70+
71+| Argument | Description |
72+|----------|-------------|
73+| `<domain>` | The domain name to set the secret for |
74+| `<key>` | The secret key (environment variable name) |
75+| `<value>` | The secret value |
76+
77+### Options
78+
79+| Option | Description |
80+|--------|-------------|
81+| `--remote` | Remote Gordon URL |
82+| `--token` | Authentication token for remote |
83+
84+### Examples
85+
86+```bash
87+# Local
88+gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/db"
89+gordon secrets set myapp.local API_KEY "your-api-key"
90+
91+# Remote
92+gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote https://gordon.mydomain.com --token $TOKEN
93+```
94+
95+---
96+
97+## gordon secrets remove
98+
99+Remove a secret from a domain.
100+
101+```bash
102+gordon secrets remove <domain> <key>
103+```
104+
105+### Arguments
106+
107+| Argument | Description |
108+|----------|-------------|
109+| `<domain>` | The domain name |
110+| `<key>` | The secret key to remove |
111+
112+### Options
113+
114+| Option | Description |
115+|--------|-------------|
116+| `--remote` | Remote Gordon URL |
117+| `--token` | Authentication token for remote |
118+
119+### Examples
120+
121+```bash
122+# Local
123+gordon secrets remove myapp.local DATABASE_URL
124+
125+# Remote
126+gordon secrets remove myapp.local DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN
127+```
128+
129+---
130+
131+## Workflow Examples
132+
133+### Setting Up Application Secrets
134+
135+```bash
136+# Database connection
137+gordon secrets set myapp.local DATABASE_URL "postgres://user:pass@postgres:5432/mydb"
138+
139+# API keys
140+gordon secrets set myapp.local STRIPE_KEY "sk_live_..."
141+gordon secrets set myapp.local SENDGRID_KEY "SG..."
142+
143+# JWT secret
144+gordon secrets set myapp.local JWT_SECRET "your-jwt-secret-here"
145+
146+# Verify
147+gordon secrets list myapp.local
148+```
149+
150+### CI/CD Secret Management
151+
152+```bash
153+# In your CI/CD pipeline
154+export GORDON_REMOTE=https://gordon.mydomain.com
155+export GORDON_TOKEN=$GORDON_TOKEN
156+
157+# Update secrets before deploy
158+gordon secrets set myapp.example.com DATABASE_URL "$DATABASE_URL"
159+gordon secrets set myapp.example.com API_KEY "$API_KEY"
160+
161+# Deploy
162+gordon routes deploy myapp.example.com
163+```
164+
165+### Rotating Secrets
166+
167+```bash
168+# Generate new secret
169+NEW_JWT_SECRET=$(openssl rand -base64 32)
170+
171+# Update the secret
172+gordon secrets set myapp.local JWT_SECRET "$NEW_JWT_SECRET"
173+
174+# Redeploy to pick up new secret
175+gordon routes deploy myapp.local
176+```
177+
178+## Related
179+
180+- [CLI Overview](./index.md)
181+- [Secrets Configuration](../config/secrets.md)
182+- [Environment Variables](../config/env.md)
A docs/cli/serve.md +291 -0
@@ -0,0 +1,291 @@
1+# Server Commands
2+
3+Commands for running and managing the Gordon server process.
4+
5+## gordon serve
6+
7+Start the Gordon server with registry and proxy components.
8+
9+### Synopsis
10+
11+```bash
12+gordon serve [options]
13+```
14+
15+### Options
16+
17+| Option | Short | Default | Description |
18+|--------|-------|---------|-------------|
19+| `--config` | `-c` | Auto-detected | Path to configuration file |
20+
21+### Description
22+
23+Starts the Gordon server, which includes:
24+
25+- **Container Registry** - Receives image pushes on the registry port
26+- **HTTP Proxy** - Routes traffic to containers on the proxy port
27+- **Event Bus** - Coordinates deployments and updates
28+- **Config Watcher** - Monitors configuration file for changes
29+
30+### Configuration File Detection
31+
32+Gordon looks for configuration in this order:
33+
34+1. Path specified with `--config`
35+2. `/etc/gordon/gordon.toml`
36+3. `~/.config/gordon/gordon.toml`
37+4. `./gordon.toml`
38+
39+### First Run
40+
41+On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
42+
43+```bash
44+# First run - creates default config
45+gordon serve
46+# Edit the config, then restart
47+```
48+
49+### Examples
50+
51+```bash
52+# Basic start
53+gordon serve
54+
55+# With custom config
56+gordon serve --config /path/to/gordon.toml
57+gordon serve -c ./my-config.toml
58+
59+# With environment override
60+GORDON_SERVER_PORT=8080 gordon serve
61+GORDON_LOGGING_LEVEL=debug gordon serve
62+```
63+
64+### Signals
65+
66+Gordon responds to these signals:
67+
68+| Signal | Action |
69+|--------|--------|
70+| `SIGTERM` | Graceful shutdown |
71+| `SIGINT` | Graceful shutdown (Ctrl+C) |
72+| `SIGUSR1` | Reload configuration |
73+| `SIGUSR2` | Manual deploy (used by `gordon deploy`) |
74+
75+### Running with systemd
76+
77+```bash
78+# Create user service
79+mkdir -p ~/.config/systemd/user
80+cat > ~/.config/systemd/user/gordon.service <<EOF
81+[Unit]
82+Description=Gordon Container Platform
83+
84+[Service]
85+Type=simple
86+Restart=always
87+ExecStart=/usr/local/bin/gordon serve
88+
89+[Install]
90+WantedBy=default.target
91+EOF
92+
93+# Enable and start
94+systemctl --user daemon-reload
95+systemctl --user enable --now gordon
96+sudo loginctl enable-linger $USER
97+```
98+
99+### Startup Sequence
100+
101+1. Load configuration
102+2. Initialize logger
103+3. Create PID file
104+4. Connect to Docker/Podman runtime
105+5. Create storage directories
106+6. Initialize services (registry, proxy, auth)
107+7. Register event handlers
108+8. Start config file watcher
109+9. Sync existing containers
110+10. Start HTTP servers
111+
112+### Shutdown Sequence
113+
114+1. Receive shutdown signal
115+2. Stop accepting new requests
116+3. Complete in-flight requests
117+4. Stop managed containers (if configured)
118+5. Remove PID file
119+6. Exit
120+
121+---
122+
123+## gordon reload
124+
125+Reload configuration and sync containers to match.
126+
127+### Synopsis
128+
129+```bash
130+gordon reload
131+```
132+
133+### Description
134+
135+Sends `SIGUSR1` to the running Gordon process, triggering:
136+
137+- Configuration file reload
138+- Route synchronization
139+- Deployment of containers for routes missing containers
140+- Attachment deployment
141+
142+### Example
143+
144+```bash
145+# After editing gordon.toml, apply changes without restart
146+vim ~/.config/gordon/gordon.toml
147+gordon reload
148+```
149+
150+---
151+
152+## gordon deploy
153+
154+Manually deploy or redeploy a specific route.
155+
156+### Synopsis
157+
158+```bash
159+gordon deploy <domain> [options]
160+```
161+
162+### Arguments
163+
164+| Argument | Description |
165+|----------|-------------|
166+| `<domain>` | The domain name of the route to deploy (required) |
167+
168+### Options
169+
170+| Option | Description |
171+|--------|-------------|
172+| `--remote` | Remote Gordon URL |
173+| `--token` | Authentication token for remote |
174+
175+### Description
176+
177+**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
178+
179+**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
180+
181+Both modes trigger:
182+
183+- Fresh image pull (always pulls latest, ignoring cache)
184+- Container redeployment for the specified route
185+
186+### Examples
187+
188+```bash
189+# Local deployment
190+gordon deploy myapp.example.com
191+gordon deploy api.example.com
192+
193+# Remote deployment
194+gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
195+```
196+
197+### Use Cases
198+
199+- Recover from a failed deployment
200+- Force redeploy without pushing a new image
201+- Manual deployment when automatic deploy didn't trigger
202+- Trigger deployments on remote Gordon instances from CI/CD
203+
204+---
205+
206+## gordon logs
207+
208+Display Gordon process logs or container logs.
209+
210+### Synopsis
211+
212+```bash
213+gordon logs [domain] [options]
214+```
215+
216+### Arguments
217+
218+| Argument | Description |
219+|----------|-------------|
220+| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
221+
222+### Options
223+
224+| Option | Short | Default | Description |
225+|--------|-------|---------|-------------|
226+| `--config` | `-c` | Auto | Path to config file |
227+| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
228+| `--lines` | `-n` | 50 | Number of lines to show |
229+| `--remote` | | | Remote Gordon URL |
230+| `--token` | | | Authentication token for remote |
231+
232+### Examples
233+
234+```bash
235+# Gordon process logs
236+gordon logs # Last 50 lines
237+gordon logs -f # Follow logs
238+gordon logs -n 100 # Last 100 lines
239+gordon logs -f -n 200 # Follow, starting from last 200 lines
240+
241+# Container logs
242+gordon logs myapp.local # Last 50 lines from container
243+gordon logs myapp.local -f # Follow container logs
244+gordon logs myapp.local -n 100 # Last 100 lines from container
245+
246+# Remote mode
247+gordon logs --remote https://gordon.mydomain.com --token $TOKEN
248+gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN
249+```
250+
251+### Log Locations
252+
253+```bash
254+# Using gordon logs
255+gordon logs -f
256+
257+# Direct file access
258+tail -f ~/.gordon/logs/gordon.log
259+
260+# With systemd
261+journalctl --user -u gordon -f
262+
263+# Container logs via docker (local alternative)
264+docker logs --tail 50 myapp.local
265+docker logs -f myapp.local
266+```
267+
268+---
269+
270+## gordon version
271+
272+Print version information.
273+
274+### Synopsis
275+
276+```bash
277+gordon version
278+```
279+
280+### Output
281+
282+```
283+Gordon v2.0.0
284+Commit: abc1234
285+Build Date: 2024-01-15
286+```
287+
288+## Related
289+
290+- [CLI Overview](./index.md)
291+- [Configuration Reference](../config/index.md)
@@ -0,0 +1,291 @@
1+# Server Commands
2+
3+Commands for running and managing the Gordon server process.
4+
5+## gordon serve
6+
7+Start the Gordon server with registry and proxy components.
8+
9+### Synopsis
10+
11+```bash
12+gordon serve [options]
13+```
14+
15+### Options
16+
17+| Option | Short | Default | Description |
18+|--------|-------|---------|-------------|
19+| `--config` | `-c` | Auto-detected | Path to configuration file |
20+
21+### Description
22+
23+Starts the Gordon server, which includes:
24+
25+- **Container Registry** - Receives image pushes on the registry port
26+- **HTTP Proxy** - Routes traffic to containers on the proxy port
27+- **Event Bus** - Coordinates deployments and updates
28+- **Config Watcher** - Monitors configuration file for changes
29+
30+### Configuration File Detection
31+
32+Gordon looks for configuration in this order:
33+
34+1. Path specified with `--config`
35+2. `/etc/gordon/gordon.toml`
36+3. `~/.config/gordon/gordon.toml`
37+4. `./gordon.toml`
38+
39+### First Run
40+
41+On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
42+
43+```bash
44+# First run - creates default config
45+gordon serve
46+# Edit the config, then restart
47+```
48+
49+### Examples
50+
51+```bash
52+# Basic start
53+gordon serve
54+
55+# With custom config
56+gordon serve --config /path/to/gordon.toml
57+gordon serve -c ./my-config.toml
58+
59+# With environment override
60+GORDON_SERVER_PORT=8080 gordon serve
61+GORDON_LOGGING_LEVEL=debug gordon serve
62+```
63+
64+### Signals
65+
66+Gordon responds to these signals:
67+
68+| Signal | Action |
69+|--------|--------|
70+| `SIGTERM` | Graceful shutdown |
71+| `SIGINT` | Graceful shutdown (Ctrl+C) |
72+| `SIGUSR1` | Reload configuration |
73+| `SIGUSR2` | Manual deploy (used by `gordon deploy`) |
74+
75+### Running with systemd
76+
77+```bash
78+# Create user service
79+mkdir -p ~/.config/systemd/user
80+cat > ~/.config/systemd/user/gordon.service <<EOF
81+[Unit]
82+Description=Gordon Container Platform
83+
84+[Service]
85+Type=simple
86+Restart=always
87+ExecStart=/usr/local/bin/gordon serve
88+
89+[Install]
90+WantedBy=default.target
91+EOF
92+
93+# Enable and start
94+systemctl --user daemon-reload
95+systemctl --user enable --now gordon
96+sudo loginctl enable-linger $USER
97+```
98+
99+### Startup Sequence
100+
101+1. Load configuration
102+2. Initialize logger
103+3. Create PID file
104+4. Connect to Docker/Podman runtime
105+5. Create storage directories
106+6. Initialize services (registry, proxy, auth)
107+7. Register event handlers
108+8. Start config file watcher
109+9. Sync existing containers
110+10. Start HTTP servers
111+
112+### Shutdown Sequence
113+
114+1. Receive shutdown signal
115+2. Stop accepting new requests
116+3. Complete in-flight requests
117+4. Stop managed containers (if configured)
118+5. Remove PID file
119+6. Exit
120+
121+---
122+
123+## gordon reload
124+
125+Reload configuration and sync containers to match.
126+
127+### Synopsis
128+
129+```bash
130+gordon reload
131+```
132+
133+### Description
134+
135+Sends `SIGUSR1` to the running Gordon process, triggering:
136+
137+- Configuration file reload
138+- Route synchronization
139+- Deployment of containers for routes missing containers
140+- Attachment deployment
141+
142+### Example
143+
144+```bash
145+# After editing gordon.toml, apply changes without restart
146+vim ~/.config/gordon/gordon.toml
147+gordon reload
148+```
149+
150+---
151+
152+## gordon deploy
153+
154+Manually deploy or redeploy a specific route.
155+
156+### Synopsis
157+
158+```bash
159+gordon deploy <domain> [options]
160+```
161+
162+### Arguments
163+
164+| Argument | Description |
165+|----------|-------------|
166+| `<domain>` | The domain name of the route to deploy (required) |
167+
168+### Options
169+
170+| Option | Description |
171+|--------|-------------|
172+| `--remote` | Remote Gordon URL |
173+| `--token` | Authentication token for remote |
174+
175+### Description
176+
177+**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
178+
179+**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
180+
181+Both modes trigger:
182+
183+- Fresh image pull (always pulls latest, ignoring cache)
184+- Container redeployment for the specified route
185+
186+### Examples
187+
188+```bash
189+# Local deployment
190+gordon deploy myapp.example.com
191+gordon deploy api.example.com
192+
193+# Remote deployment
194+gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
195+```
196+
197+### Use Cases
198+
199+- Recover from a failed deployment
200+- Force redeploy without pushing a new image
201+- Manual deployment when automatic deploy didn't trigger
202+- Trigger deployments on remote Gordon instances from CI/CD
203+
204+---
205+
206+## gordon logs
207+
208+Display Gordon process logs or container logs.
209+
210+### Synopsis
211+
212+```bash
213+gordon logs [domain] [options]
214+```
215+
216+### Arguments
217+
218+| Argument | Description |
219+|----------|-------------|
220+| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
221+
222+### Options
223+
224+| Option | Short | Default | Description |
225+|--------|-------|---------|-------------|
226+| `--config` | `-c` | Auto | Path to config file |
227+| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
228+| `--lines` | `-n` | 50 | Number of lines to show |
229+| `--remote` | | | Remote Gordon URL |
230+| `--token` | | | Authentication token for remote |
231+
232+### Examples
233+
234+```bash
235+# Gordon process logs
236+gordon logs # Last 50 lines
237+gordon logs -f # Follow logs
238+gordon logs -n 100 # Last 100 lines
239+gordon logs -f -n 200 # Follow, starting from last 200 lines
240+
241+# Container logs
242+gordon logs myapp.local # Last 50 lines from container
243+gordon logs myapp.local -f # Follow container logs
244+gordon logs myapp.local -n 100 # Last 100 lines from container
245+
246+# Remote mode
247+gordon logs --remote https://gordon.mydomain.com --token $TOKEN
248+gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN
249+```
250+
251+### Log Locations
252+
253+```bash
254+# Using gordon logs
255+gordon logs -f
256+
257+# Direct file access
258+tail -f ~/.gordon/logs/gordon.log
259+
260+# With systemd
261+journalctl --user -u gordon -f
262+
263+# Container logs via docker (local alternative)
264+docker logs --tail 50 myapp.local
265+docker logs -f myapp.local
266+```
267+
268+---
269+
270+## gordon version
271+
272+Print version information.
273+
274+### Synopsis
275+
276+```bash
277+gordon version
278+```
279+
280+### Output
281+
282+```
283+Gordon v2.0.0
284+Commit: abc1234
285+Build Date: 2024-01-15
286+```
287+
288+## Related
289+
290+- [CLI Overview](./index.md)
291+- [Configuration Reference](../config/index.md)

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close