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 via --remote flag
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 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

# 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 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

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 via `--remote` flag
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 reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) |
27| `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
28| `gordon status` | Show Gordon server status | [status](./status.md) |
29
30## Client Commands
31
32| Command | Description | Documentation |
33|---------|-------------|---------------|
34| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
35| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
36| `gordon completion` | Generate shell autocompletion scripts | - |
37
38## Quick Reference
39
40```bash
41# Start Gordon
42gordon serve
43gordon serve --config /path/to/config.toml
44
45# Reload configuration
46gordon reload
47
48# Deploy a specific route
49gordon deploy myapp.example.com
50
51# View logs
52gordon logs                          # Gordon process logs
53gordon logs -f                       # Follow process logs
54gordon logs -n 100                   # Last 100 lines
55gordon logs myapp.local              # Container logs for myapp.local
56gordon logs myapp.local -f           # Follow container logs
57
58# Check version
59gordon version
60
61# Authentication
62gordon auth token generate --subject ci-bot --expiry 0
63gordon auth token list
64gordon auth token revoke <token-id>
65gordon auth password hash
66gordon auth internal
67
68# Routes
69gordon routes list
70gordon routes add myapp.example.com myapp:latest
71gordon routes remove myapp.example.com
72gordon routes deploy myapp.example.com
73
74# Attachments
75gordon attachments list
76gordon attachments add app.example.com postgres:18
77gordon attachments remove app.example.com postgres:18
78
79# Secrets
80gordon secrets list myapp.local
81gordon secrets set myapp.local DATABASE_URL "postgres://..."
82gordon secrets remove myapp.local DATABASE_URL
83
84# Remotes
85gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
86gordon remotes list
87gordon remotes use prod
88```
89
90## Global Options
91
92| Option | Description |
93|--------|-------------|
94| `-c, --config` | Path to configuration file |
95| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
96| `--token` | Authentication token for remote |
97
98### Remote Targeting
99
100The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
101
102**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.
103
104```bash
105# Using flags (use the gordon_domain from remote Gordon config)
106gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
107
108# Using environment variables
109export GORDON_REMOTE=https://gordon.mydomain.com
110export GORDON_TOKEN=$TOKEN
111gordon routes list
112```
113
114## Exit Codes
115
116| Code | Meaning |
117|------|---------|
118| 0 | Success |
119| 1 | General error |
120| 2 | Configuration error |
121
122## Environment Variables
123
124Gordon reads configuration from environment variables:
125
126```bash
127GORDON_SERVER_PORT=8080 gordon serve
128GORDON_LOGGING_LEVEL=debug gordon serve
129```
130
131Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
132
133## Related
134
135- [Core Concepts](../concepts.md)
136- [Configuration Reference](../config/index.md)

index.md RawHistoryFolder