commands.md Raw History Folder

CLI Commands

Gordon provides a command-line interface for server management, deployment, and authentication.

Commands Overview

Command	Description
`gordon serve`	Start the Gordon server
`gordon reload`	Reload configuration and sync containers
`gordon deploy`	Manually deploy or redeploy a specific route
`gordon logs`	Display Gordon process or container logs
`gordon version`	Print version information
`gordon auth`	Manage registry authentication
`gordon routes`	Manage routes (local or remote)
`gordon secrets`	Manage secrets (local or remote)
`gordon remotes`	Manage saved remote Gordon instances

Quick Reference

# Start Gordon
gordon serve
gordon serve --config /path/to/config.toml

# Reload configuration
gordon reload

# Deploy a specific route
gordon deploy myapp.example.com

# View logs
gordon logs                          # Gordon process logs
gordon logs -f                       # Follow process logs
gordon logs -n 100                   # Last 100 lines
gordon logs myapp.local              # Container logs for myapp.local
gordon logs myapp.local -f           # Follow container logs

# Check version
gordon version

# Authentication
gordon auth token generate --subject ci-bot --expiry 0
gordon auth token list
gordon auth token revoke <token-id>
gordon auth password hash
gordon auth internal

Global Options

Option	Description
`-c, --config`	Path to configuration file
`--remote`	Remote Gordon URL (e.g., `https://gordon.mydomain.com`)
`--token`	Authentication token for remote

Remote Targeting

The CLI can target remote Gordon instances using the --remote flag or GORDON_REMOTE environment variable.

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.

# Using flags (use the gordon_domain from remote Gordon config)
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

# Using environment variables
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=$TOKEN
gordon routes list

gordon serve

Start the Gordon server with registry and proxy components.

Synopsis

gordon serve [options]

Options

Option	Short	Default	Description
`--config`	`-c`	Auto-detected	Path to configuration file

Description

Starts the Gordon server, which includes:

Container Registry - Receives image pushes on the registry port
HTTP Proxy - Routes traffic to containers on the proxy port
Event Bus - Coordinates deployments and updates
Config Watcher - Monitors configuration file for changes

Configuration File Detection

Gordon looks for configuration in this order:

Path specified with --config
/etc/gordon/gordon.toml
~/.config/gordon/gordon.toml
./gordon.toml

First Run

On first run without a config file, Gordon creates a default configuration at ~/.config/gordon/gordon.toml.

# First run - creates default config
gordon serve
# Edit the config, then restart

Examples

# Basic start
gordon serve

# With custom config
gordon serve --config /path/to/gordon.toml
gordon serve -c ./my-config.toml

# With environment override
GORDON_SERVER_PORT=8080 gordon serve
GORDON_LOGGING_LEVEL=debug gordon serve

Signals

Gordon responds to these signals:

Signal	Action
`SIGTERM`	Graceful shutdown
`SIGINT`	Graceful shutdown (Ctrl+C)
`SIGUSR1`	Reload configuration
`SIGUSR2`	Manual deploy (used by `gordon deploy`)

Running with systemd

# Create user service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gordon.service <<EOF
[Unit]
Description=Gordon Container Platform

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/gordon serve

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now gordon
sudo loginctl enable-linger $USER

Startup Sequence

Load configuration
Initialize logger
Create PID file
Connect to Docker/Podman runtime
Create storage directories
Initialize services (registry, proxy, auth)
Register event handlers
Start config file watcher
Sync existing containers
Start HTTP servers

Shutdown Sequence

Receive shutdown signal
Stop accepting new requests
Complete in-flight requests
Stop managed containers (if configured)
Remove PID file
Exit

gordon reload

Reload configuration and sync containers to match.

Synopsis

gordon reload

Description

Sends SIGUSR1 to the running Gordon process, triggering:

Configuration file reload
Route synchronization
Deployment of containers for routes missing containers
Attachment deployment

Example

# After editing gordon.toml, apply changes without restart
vim ~/.config/gordon/gordon.toml
gordon reload

gordon deploy

Manually deploy or redeploy a specific route.

Synopsis

gordon deploy <domain> [options]

Arguments

Argument	Description
`<domain>`	The domain name of the route to deploy (required)

Options

Option	Description
`--remote`	Remote Gordon URL
`--token`	Authentication token for remote

Description

Local mode: Sends SIGUSR2 to the Gordon process with the specified domain.

Remote mode: Calls the remote Gordon Admin API to trigger deployment.

Both modes trigger:

Fresh image pull (always pulls latest, ignoring cache)
Container redeployment for the specified route

Examples

# Local deployment
gordon deploy myapp.example.com
gordon deploy api.example.com

# Remote deployment
gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN

Use Cases

Recover from a failed deployment
Force redeploy without pushing a new image
Manual deployment when automatic deploy didn't trigger
Trigger deployments on remote Gordon instances from CI/CD

gordon logs

Display Gordon process logs or container logs.

Synopsis

gordon logs [domain] [options]

Arguments

Argument	Description
`[domain]`	Optional. Container domain to view logs for. Without this, shows Gordon process logs.

Options

Option	Short	Default	Description
`--config`	`-c`	Auto	Path to config file
`--follow`	`-f`	false	Follow log output (like `tail -f`)
`--lines`	`-n`	50	Number of lines to show
`--remote`			Remote Gordon URL
`--token`			Authentication token for remote

Examples

# Gordon process logs
gordon logs              # Last 50 lines
gordon logs -f           # Follow logs
gordon logs -n 100       # Last 100 lines
gordon logs -f -n 200    # Follow, starting from last 200 lines

# Container logs
gordon logs myapp.local           # Last 50 lines from container
gordon logs myapp.local -f        # Follow container logs
gordon logs myapp.local -n 100    # Last 100 lines from container

# Remote mode
gordon logs --remote https://gordon.mydomain.com --token $TOKEN
gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN

Log Locations

# Using gordon logs
gordon logs -f

# Direct file access
tail -f ~/.gordon/logs/gordon.log

# With systemd
journalctl --user -u gordon -f

# Container logs via docker (local alternative)
docker logs --tail 50 myapp.local
docker logs -f myapp.local

gordon version

Print version information.

Synopsis

gordon version

Output

Gordon v2.0.0
Commit: abc1234
Build Date: 2024-01-15

gordon auth

Manage registry authentication tokens and passwords.

Subcommands

Subcommand	Description
`token generate`	Generate a new JWT token
`token list`	List all stored tokens
`token revoke`	Revoke a token by ID
`password hash`	Generate bcrypt password hash
`internal`	Show internal registry credentials

gordon auth token generate

Generate a new JWT authentication token for registry access.

gordon auth token generate --subject <name> [options]

Options:

Option	Default	Description
`--subject`	(required)	Username/subject for the token
`--scopes`	`push,pull`	Comma-separated scopes
`--expiry`	`30d`	Duration until expiry (0 = never)
`-c, --config`	Auto	Path to config file

Duration format:

Supports human-friendly duration units:

Unit	Description	Example
`d`	Days (24 hours)	`30d`
`w`	Weeks (7 days)	`2w`
`M`	Months (30 days)	`6M`
`y`	Years (365 days)	`1y`

Compound durations are also supported: 1y6M, 2w3d, 1d12h

Standard Go durations also work: 24h, 30m, 1h30m

Examples:

# CI token that never expires
gordon auth token generate --subject github-actions --expiry 0

# Read-only token for 30 days
gordon auth token generate --subject reader --scopes pull --expiry 30d

# Push-only token for 1 year
gordon auth token generate --subject builder --scopes push --expiry 1y

# Temporary token (24 hours)
gordon auth token generate --subject temp --expiry 24h

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

Output:

Token generated successfully!
Subject: github-actions
Scopes: push, pull
Expiry: never

Token (use as password with docker login):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Usage: docker login -u github-actions -p <token> <registry>

gordon auth token list

List all stored authentication tokens.

gordon auth token list [options]

Output:

ID                                    Subject               Expires               Revoked
------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890  github-actions        never                 no
b2c3d4e5-f6a7-8901-bcde-f12345678901  deploy-bot            2024-02-15 10:30      no
c3d4e5f6-a7b8-9012-cdef-123456789012  old-token             2024-01-01 00:00      yes

gordon auth token revoke

Revoke a token by its ID.

gordon auth token revoke <token-id> [options]

Example:

gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890

Output:

Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.

gordon auth password hash

Generate a bcrypt hash for password authentication.

gordon auth password hash

Interactively prompts for a password and outputs the bcrypt hash.

Output:

Enter password: ********

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

Then reference the path in your config:
  [registry_auth]
  type = "password"
  password_hash = "gordon/registry/password_hash"

gordon auth internal

Display the auto-generated internal registry credentials.

gordon auth internal

Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.

Output:

Internal Registry Credentials
==============================
Username: gordon-internal
Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...

Usage:
  docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...

Notes:

Credentials are regenerated each time Gordon starts
Only available while Gordon is running
Used for manual docker pull from the local registry during debugging

Use cases:

Debugging image pull failures
Manual recovery after deployment issues
Inspecting images in the local registry

Token Scopes

Scope	Permission
`push`	Push images to registry
`pull`	Pull images from registry
`push,pull`	Both push and pull (default)

Token Expiry Formats

Format	Duration
`0`	Never expires
`24h`	24 hours
`720h`	30 days
`8760h`	1 year

Workflow Examples

CI/CD Setup

# Generate token for CI
gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0

# Save token as CI secret
# GitHub: Settings → Secrets → New repository secret
# GitLab: Settings → CI/CD → Variables

# Using generated token
docker login -u ci-bot -p <token> registry.mydomain.com

# In CI/CD
echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com

Token Rotation

# Generate new token
gordon auth token generate --subject ci-bot --expiry 0

# Update CI secrets with new token

# Revoke old token
gordon auth token revoke <old-token-id>

Password Setup

# Generate hash
gordon auth password hash
# Enter: mypassword

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

# Configure gordon.toml
[registry_auth]
enabled = true
type = "password"
username = "deploy"
password_hash = "gordon/registry/password_hash"

gordon routes

Manage routes on local or remote Gordon instances.

Subcommands

Subcommand	Description
`list`	List all routes
`add`	Add a new route
`remove`	Remove a route
`deploy`	Deploy a specific route

gordon routes list

List all configured routes.

gordon routes list
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

gordon routes add

Add a new route.

gordon routes add <domain> <image>
gordon routes add myapp.example.com myapp:latest

gordon routes remove

Remove a route.

gordon routes remove <domain>
gordon routes remove myapp.example.com

gordon routes deploy

Deploy or redeploy a specific route.

gordon routes deploy <domain>
gordon routes deploy myapp.example.com

gordon secrets

Manage secrets on local or remote Gordon instances.

Subcommands

Subcommand	Description
`list`	List all secrets for a domain
`set`	Set a secret value
`remove`	Remove a secret

Examples

# Local mode (reads/writes secrets directly)
gordon secrets list myapp.local
gordon secrets set myapp.local DATABASE_URL "postgres://..."
gordon secrets remove myapp.local DATABASE_URL

# Remote mode
gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote ... --token ...
gordon secrets remove myapp.local DATABASE_URL --remote ... --token ...

gordon remotes

Manage saved remote Gordon instances for easier CLI usage.

Subcommands

Subcommand	Description
`list`	List saved remotes
`add`	Add a new remote
`remove`	Remove a saved remote
`use`	Set active remote

Examples

# Add a remote
gordon remotes add prod https://gordon.mydomain.com --token $TOKEN

# List saved remotes
gordon remotes list

# Set active remote
gordon remotes use prod

# Now use without --remote flag
gordon routes list

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error

Environment Variables

Gordon reads configuration from environment variables:

GORDON_SERVER_PORT=8080 gordon serve
GORDON_LOGGING_LEVEL=debug gordon serve

Pattern: GORDON_SECTION_KEY (uppercase, underscores)

source

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

commands.md RawHistoryFolder

CLI Commands

Commands Overview

Quick Reference

Global Options

Remote Targeting

gordon serve

Synopsis

Options

Description

Configuration File Detection

First Run

Examples

Signals

Running with systemd

Startup Sequence

Shutdown Sequence

gordon reload

Synopsis

Description

Example

gordon deploy

Synopsis

Arguments

Options

Description

Examples

Use Cases

gordon logs

Synopsis

Arguments

Options

Examples

Log Locations

gordon version

Synopsis

Output

gordon auth

Subcommands

gordon auth token generate

gordon auth token list

gordon auth token revoke

gordon auth password hash

gordon auth internal

Token Scopes

Token Expiry Formats

Workflow Examples

CI/CD Setup

Docker Login

Token Rotation

Password Setup

gordon routes

Subcommands

gordon routes list

gordon routes add

gordon routes remove

gordon routes deploy

gordon secrets

Subcommands

Examples

gordon remotes

Subcommands

Examples

Exit Codes

Environment Variables

Related

commands.md Raw History Folder