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 daemon` | Daemon status, logs, reload, config, TLS, traffic, and networks | [daemon](./daemon.md) |
30| `gordon images` | Push, list, and prune images | [images](./images.md) |
31| `gordon volumes` | Manage volumes | [volumes](./volumes.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 installation configuration (never activates app state)
49gordon daemon reload
50
51# Applications (daemon-owned; fail without a reachable daemon)
52gordon apps apply --file blog.toml
53gordon apps apply --file blog.toml --deploy
54gordon apps list
55gordon apps show blog
56gordon apps diff blog
57gordon apps deploy blog
58gordon apps restart blog
59gordon apps stop blog
60gordon apps start blog
61gordon apps remove blog
62gordon apps operations show blog --key <operation-key>
63gordon apps operations watch blog --key <operation-key>
64gordon apps secrets list blog
65
66# Daemon
67gordon daemon status
68gordon daemon config show
69gordon daemon config validate --file /path/to/gordon.toml
70gordon daemon tls
71gordon daemon networks
72
73# Push an image (OCI transfer only; deploy separately)
74gordon images push myapp --build --remote prod
75
76# View logs
77gordon daemon logs                                      # Gordon process logs
78gordon daemon logs -f                                   # Follow process logs
79gordon daemon logs -n 100                               # Last 100 process-log lines
80gordon apps logs blog --service web              # App service logs
81gordon apps logs blog --service web --follow     # Follow app service logs
82
83# Check version
84gordon version
85
86# Traffic plane
87gordon daemon traffic --remote prod
88gordon daemon traffic --remote prod --json
89
90# Backups
91gordon backups list
92gordon backups run shop --service api --database orders
93gordon backups volume run shop --service api --volume data
94gordon backups status
95
96# Images
97gordon images push myapp --build --remote prod
98gordon images list
99gordon images prune --dry-run
100gordon images prune --keep-releases 3
101
102# Authentication
103gordon auth login --remote https://gordon.example.com --token $TOKEN
104gordon auth status
105gordon auth show-token
106gordon auth logout
107gordon auth token generate --subject ci-bot --expiry 0
108gordon auth token list
109gordon auth token revoke <token-id>
110gordon auth internal
111
112# Remotes
113gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
114gordon remotes list
115gordon remotes use prod
116
117# Volumes
118gordon volumes list
119gordon volumes prune
120```
121
122## Global Options
123
124| Option | Description |
125|--------|-------------|
126| `-c, --config` | Path to configuration file |
127| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
128| `--token` | Authentication token for remote |
129| `--insecure` | Skip TLS certificate verification for remote HTTPS endpoints |
130
131### Remote Targeting
132
133The CLI can target remote Gordon instances using client config, an active remote, `--remote`,
134or `GORDON_REMOTE` environment variable. Use `--remote` and `--token` as global overrides
135when you want to bypass your saved configuration.
136
137When no explicit remote is selected and no active remote is configured, Gordon can
138**auto-infer a saved remote** for `gordon images push`. It probes your saved remotes and uses the
139remote automatically when exactly one matches. If multiple remotes match, Gordon stops with
140an ambiguity error and asks you to use `--remote`. If any remote probe fails, Gordon also
141stops rather than guessing.
142
143```bash
144# Auto-inferred single match from saved remotes
145gordon images push myapp --build
146```
147
148**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.
149
150Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
151You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
152or in a specific entry in `~/.config/gordon/remotes.toml`.
153
154```bash
155# Using flags (use the gordon_domain from remote Gordon config)
156gordon daemon status --remote https://gordon.example.com --token $TOKEN
157
158# Against self-signed/private CA endpoint
159gordon --remote https://gordon.example.com --token $TOKEN --insecure daemon status
160
161# Using environment variables
162export GORDON_REMOTE=https://gordon.example.com
163export GORDON_TOKEN=$TOKEN
164export GORDON_INSECURE=true
165gordon daemon status
166```
167
168## Exit Codes
169
170| Code | Meaning |
171|------|---------|
172| 0 | Success |
173| 1 | General error |
174| 2 | Configuration error |
175
176## Environment Variables
177
178Gordon reads configuration from environment variables:
179
180```bash
181GORDON_LOGGING_LEVEL=debug gordon serve
182```
183
184Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
185
186## Related
187
188- [Core Concepts](../concepts.md)
189- [Configuration Reference](../config/index.md)