CLI Commands

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

Commands are organized by where they run:

Server Commands - Must run on the machine hosting Gordon
Management Commands - Work locally or remotely
Client Commands - CLI utilities that don't require a running Gordon server

Server Commands (local only)

Command	Description	Documentation
`gordon serve`	Start the Gordon server	serve
`gordon auth`	Manage Gordon server authentication	auth

Management Commands (local or remote)

Command	Description	Documentation
`gordon routes`	Manage routes	routes
`gordon attachments`	Manage container attachments	attachments
`gordon secrets`	Manage secrets	secrets
`gordon deploy`	Manually deploy or redeploy a route	serve
`gordon restart`	Restart a running container	restart
`gordon push`	Tag, push, and optionally deploy an image	push
`gordon rollback`	Roll back to a previous image tag	rollback
`gordon reload`	Reload configuration and sync containers	serve
`gordon logs`	Display Gordon process or container logs	serve
`gordon status`	Show Gordon server status	status

Client Commands

Command	Description	Documentation
`gordon remotes`	Manage saved remote Gordon instances	remotes
`gordon version`	Print version information	serve
`gordon completion`	Generate shell autocompletion scripts	-

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

# Restart a running container
gordon restart myapp.example.com

# Push an image and deploy
gordon push myapp.example.com --build

# Push and deploy without confirmation
gordon push myapp.example.com --no-confirm

# Roll back to a previous tag
gordon rollback 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

# Routes
gordon routes list
gordon routes add myapp.example.com myapp:latest
gordon routes remove myapp.example.com
gordon routes deploy myapp.example.com

# Attachments
gordon attachments list
gordon attachments add app.example.com postgres:18
gordon attachments remove app.example.com postgres:18

# Secrets
gordon secrets list myapp.local
gordon secrets set myapp.local DATABASE_URL "postgres://..."
gordon secrets remove myapp.local DATABASE_URL

# Remotes
gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
gordon remotes list
gordon remotes use prod

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 client config, an active remote, --remote, or GORDON_REMOTE environment variable. Use --remote and --token as global overrides when you want to bypass your saved configuration.

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

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
5Commands are organized by where they run:
6
7- **Server Commands** - Must run on the machine hosting Gordon
8- **Management Commands** - Work locally or remotely
9- **Client Commands** - CLI utilities that don't require a running Gordon server
10
11## Server Commands (local only)
12
13| Command | Description | Documentation |
14|---------|-------------|---------------|
15| `gordon serve` | Start the Gordon server | [serve](./serve.md) |
16| `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) |
17
18## Management Commands (local or remote)
19
20| Command | Description | Documentation |
21|---------|-------------|---------------|
22| `gordon routes` | Manage routes | [routes](./routes.md) |
23| `gordon attachments` | Manage container attachments | [attachments](./attachments.md) |
24| `gordon secrets` | Manage secrets | [secrets](./secrets.md) |
25| `gordon deploy` | Manually deploy or redeploy a route | [serve](./serve.md#gordon-deploy) |
26| `gordon restart` | Restart a running container | [restart](./restart.md) |
27| `gordon push` | Tag, push, and optionally deploy an image | [push](./push.md) |
28| `gordon rollback` | Roll back to a previous image tag | [rollback](./rollback.md) |
29| `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) |
30| `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
31| `gordon status` | Show Gordon server status | [status](./status.md) |
32
33## Client Commands
34
35| Command | Description | Documentation |
36|---------|-------------|---------------|
37| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
38| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
39| `gordon completion` | Generate shell autocompletion scripts | - |
40
41## Quick Reference
42
43```bash
44# Start Gordon
45gordon serve
46gordon serve --config /path/to/config.toml
47
48# Reload configuration
49gordon reload
50
51# Deploy a specific route
52gordon deploy myapp.example.com
53
54# Restart a running container
55gordon restart myapp.example.com
56
57# Push an image and deploy
58gordon push myapp.example.com --build
59
60# Push and deploy without confirmation
61gordon push myapp.example.com --no-confirm
62
63# Roll back to a previous tag
64gordon rollback myapp.example.com
65
66# View logs
67gordon logs                          # Gordon process logs
68gordon logs -f                       # Follow process logs
69gordon logs -n 100                   # Last 100 lines
70gordon logs myapp.local              # Container logs for myapp.local
71gordon logs myapp.local -f           # Follow container logs
72
73# Check version
74gordon version
75
76# Authentication
77gordon auth token generate --subject ci-bot --expiry 0
78gordon auth token list
79gordon auth token revoke <token-id>
80gordon auth password hash
81gordon auth internal
82
83# Routes
84gordon routes list
85gordon routes add myapp.example.com myapp:latest
86gordon routes remove myapp.example.com
87gordon routes deploy myapp.example.com
88
89# Attachments
90gordon attachments list
91gordon attachments add app.example.com postgres:18
92gordon attachments remove app.example.com postgres:18
93
94# Secrets
95gordon secrets list myapp.local
96gordon secrets set myapp.local DATABASE_URL "postgres://..."
97gordon secrets remove myapp.local DATABASE_URL
98
99# Remotes
100gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
101gordon remotes list
102gordon remotes use prod
103```
104
105## Global Options
106
107| Option | Description |
108|--------|-------------|
109| `-c, --config` | Path to configuration file |
110| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
111| `--token` | Authentication token for remote |
112
113### Remote Targeting
114
115The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
116or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
117when you want to bypass your saved configuration.
118
119**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.
120
121```bash
122# Using flags (use the gordon_domain from remote Gordon config)
123gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
124
125# Using environment variables
126export GORDON_REMOTE=https://gordon.mydomain.com
127export GORDON_TOKEN=$TOKEN
128gordon routes list
129```
130
131## Exit Codes
132
133| Code | Meaning |
134|------|---------|
135| 0 | Success |
136| 1 | General error |
137| 2 | Configuration error |
138
139## Environment Variables
140
141Gordon reads configuration from environment variables:
142
143```bash
144GORDON_SERVER_PORT=8080 gordon serve
145GORDON_LOGGING_LEVEL=debug gordon serve
146```
147
148Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
149
150## Related
151
152- [Core Concepts](../concepts.md)
153- [Configuration Reference](../config/index.md)

index.md RawHistoryFolder