1# CLI Commands
2
3Gordon provides a command-line interface for server management, app deployment, and authentication.
4
5Most `list`/`show` commands also support `--json` for machine-readable output.
6
7Commands are organized by where they run:
8
9- **Server Commands** - Must run on the machine hosting Gordon
10- **Management Commands** - Work locally or remotely
11- **Client Commands** - CLI utilities that don't require a running Gordon server
12
13## Server Commands (local only)
14
15| Command | Description | Documentation |
16|---------|-------------|---------------|
17| `gordon serve` | Start the Gordon server | [serve](./serve.md) |
18| `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) |
19| `gordon ca` | Manage the internal Certificate Authority | [ca](./ca.md) |
20
21## Management Commands (local or remote)
22
23Management commands use the authenticated daemon API. By default they connect through the owner-only local Unix socket; add `--remote` to use authenticated HTTP/TLS against another Gordon instance.
24
25| Command | Description | Documentation |
26|---------|-------------|---------------|
27| `gordon apps` | Manage applications, operations, and app secrets | [apps](./apps.md) |
28| `gordon backups` | Manage declared app database and volume backups | [backup](./backup.md) |
29| `gordon config` | Show and validate server configuration | [config](./config.md) |
30| `gordon images` | List and prune images | [images](./images.md) |
31| `gordon logs` | Display Gordon process logs | [serve](./serve.md#gordon-logs) |
32| `gordon networks list` | List Gordon-managed Docker networks | [networks](./networks.md) |
33| `gordon push` | Tag and push an image (never deploys) | [push](./push.md) |
34| `gordon reload` | Reload installation configuration | [serve](./serve.md#gordon-reload) |
35| `gordon secrets` | Manage installation secrets | [secrets](./secrets.md) |
36| `gordon status` | Show Gordon server status | [status](./status.md) |
37| `gordon tls` | Inspect TLS status | [tls](./tls.md) |
38| `gordon traffic` | Inspect traffic plane status | [traffic](./traffic.md) |
39| `gordon volumes` | Manage volumes | [volumes](./volumes.md) |
40
41## Client Commands
42
43| Command | Description | Documentation |
44|---------|-------------|---------------|
45| `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) |
46| `gordon version` | Print version information | [serve](./serve.md#gordon-version) |
47| `gordon completion` | Generate shell autocompletion scripts | - |
48
49## Quick Reference
50
51```bash
52# Start Gordon
53gordon serve
54gordon serve --config /path/to/config.toml
55
56# Reload installation configuration (never activates app state)
57gordon reload
58
59# Applications (daemon-owned; fail without a reachable daemon)
60gordon apps apply --file blog.toml
61gordon apps apply --file blog.toml --deploy
62gordon apps list
63gordon apps show blog
64gordon apps diff blog
65gordon apps deploy blog
66gordon apps restart blog
67gordon apps stop blog
68gordon apps start blog
69gordon apps remove blog
70gordon apps operations show blog --key <operation-key>
71gordon apps operations watch blog --key <operation-key>
72gordon apps secrets list blog
73gordon config validate --file /path/to/gordon.toml
74
75# Push an image (OCI transfer only; deploy separately)
76gordon push myapp --build --remote prod
77
78# View logs
79gordon logs                                      # Gordon process logs
80gordon logs -f                                   # Follow process logs
81gordon logs -n 100                               # Last 100 process-log lines
82gordon apps logs blog --service web              # App service logs
83gordon apps logs blog --service web --follow     # Follow app service logs
84
85# Check version
86gordon version
87
88# Traffic plane
89gordon traffic status --remote prod
90gordon traffic status --remote prod --json
91
92# Backups
93gordon backups list
94gordon backups run shop --service api --database orders
95gordon backups volume run shop --service api --volume data
96gordon backups status
97
98# Images
99gordon images list
100gordon images prune --dry-run
101gordon images prune --keep-releases 3
102
103# Authentication
104gordon auth login --remote https://gordon.example.com --token $TOKEN
105gordon auth status
106gordon auth show-token
107gordon auth logout
108gordon auth token generate --subject ci-bot --expiry 0
109gordon auth token list
110gordon auth token revoke <token-id>
111gordon auth internal
112
113# Secrets
114gordon secrets list myapp.example.com
115gordon secrets set myapp.example.com --from-file ./app.env
116gordon secrets remove myapp.example.com DATABASE_URL
117
118# Remotes
119gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
120gordon remotes list
121gordon remotes use prod
122
123# Volumes
124gordon volumes list
125gordon volumes prune
126```
127
128## Global Options
129
130| Option | Description |
131|--------|-------------|
132| `-c, --config` | Path to configuration file |
133| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
134| `--token` | Authentication token for remote |
135| `--insecure` | Skip TLS certificate verification for remote HTTPS endpoints |
136
137### Remote Targeting
138
139The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
140or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
141when you want to bypass your saved configuration.
142
143When no explicit remote is selected and no active remote is configured, Gordon can
144**auto-infer a saved remote** for `gordon push`. It probes your saved remotes and uses the
145remote automatically when exactly one matches. If multiple remotes match, Gordon stops with
146an ambiguity error and asks you to use `--remote`. If any remote probe fails, Gordon also
147stops rather than guessing.
148
149```bash
150# Auto-inferred single match from saved remotes
151gordon push myapp --build
152```
153
154**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.
155
156Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
157You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
158or in a specific entry in `~/.config/gordon/remotes.toml`.
159
160```bash
161# Using flags (use the gordon_domain from remote Gordon config)
162gordon status --remote https://gordon.example.com --token $TOKEN
163
164# Against self-signed/private CA endpoint
165gordon --remote https://gordon.example.com --token $TOKEN --insecure status
166
167# Using environment variables
168export GORDON_REMOTE=https://gordon.example.com
169export GORDON_TOKEN=$TOKEN
170export GORDON_INSECURE=true
171gordon status
172```
173
174## Exit Codes
175
176| Code | Meaning |
177|------|---------|
178| 0 | Success |
179| 1 | General error |
180| 2 | Configuration error |
181
182## Environment Variables
183
184Gordon reads configuration from environment variables:
185
186```bash
187GORDON_LOGGING_LEVEL=debug gordon serve
188```
189
190Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
191
192## Related
193
194- [Core Concepts](../concepts.md)
195- [Configuration Reference](../config/index.md)