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