Apps Commands
Validate, persist, inspect, and operate applications.
All mutations are executed by the daemon through the admin API.
Without a reachable daemon the commands fail with daemon-unavailable
instead of writing locally. Mutations are idempotent: every request carries a
client-generated key, and the daemon binds that key to the exact request.
Repeating a key replays the recorded result; reusing it for a different request
is refused. An interrupted operation is never executed twice, so an ambiguous
outcome is re-queried by key before any retry (never retry under a fresh
key). Unknown apps are reported as app not found and create no state.
Local and remote targets
With no --remote/GORDON_REMOTE selected, commands discover the daemon's
owner-only administration socket. The CLI checks $XDG_RUNTIME_DIR/gordon/admin.sock
when set, then /run/user/<uid>/gordon/admin.sock, then ~/.gordon/run/admin.sock.
It accepts only a safe owner-owned socket. This works with auth.enabled=false:
the socket carries no bearer token and grants the local-owner principal only
app administration and app log reads. An explicit remote is authoritative and
never falls back to the socket.
See Local-only Mode.
gordon apps
Subcommands
| Subcommand |
Description |
apply |
Validate and persist an app manifest |
operations |
Inspect app operation journals |
list |
List applications |
show |
Show desired and active state for an app |
diff |
Show the normalized desired-vs-active diff |
secrets |
Manage app secret values |
deploy |
Activate an app revision |
restart |
Restart an app from pinned digests |
stop |
Stop an app (preserves all data) |
start |
Start a stopped app from active state |
remove |
Remove app workloads (volumes and secrets are retained) |
status |
Show effective vs observed state for an app |
logs |
Show logs for an app service |
gordon apps apply
gordon apps apply --file blog.toml [--dry-run] [--deploy] [--json]
Validates a manifest file and persists it as desired state (or dry-runs).
With --deploy, chains exactly the accepted revision into a deploy after
persistence succeeds; the two outcomes are reported separately because a
deploy may fail after the apply succeeded.
When the daemon accepts the deploy asynchronously (HTTP 202), the command
reuses the same by-key watch as gordon apps deploy: it polls the
operation journal until terminal, prints progress only when the operation
or step state changes, and never reissues the deploy. A terminal
partial/failed deploy exits nonzero while still reporting the
successful apply. Ctrl-C stops only local polling: the daemon-side
operation keeps running and the command prints how to resume it.
With --json, stdout carries exactly one final combined document after the
deploy reaches a terminal state:
{
"apply": { "app": "blog", "resulting_revision": "rev-b", "pending": true },
"deploy": { "op": "op-1", "app": "blog", "status": "success", "outcome": "success" }
}
No initial running document is emitted, and progress, transient warnings,
and Ctrl-C resume guidance go to stderr.
--dry-run and --deploy cannot be combined.
gordon apps list
gordon apps list [--json]
Lists applications with one row per app. States are applied when no revision is active, pending when desired state awaits activation, stopped when stopped intent is set, and otherwise active. A non-success last operation is appended to active in parentheses.
gordon apps show
gordon apps show APP [--json]
Shows desired revision and acceptance status, pending state, per-service
effective revision, container, digest, and restart safety, the resources the
app owns (volumes, secret paths, image references — never secret values),
stopped intent, and the last operation with its outcome.
gordon apps operations show
gordon apps operations show APP --key KEY [--json]
Recovers one operation journal entry by its client-generated request key.
--key is required. Use it to re-query an ambiguous mutation outcome before
retrying: repeating the same key replays the recorded result, while a key
reused for a different request is refused.
Flags
| Flag |
Description |
--key |
Request key (required) |
--json |
Output as JSON |
gordon apps operations watch
gordon apps operations watch APP --key KEY [--json]
Polls the operation journal by request key until the operation reaches a
terminal state, then renders the terminal journal. It never reissues the
mutation, so it is the safe way to resume after an interrupted deploy or to
follow an operation started elsewhere. Progress is printed only when the
operation or step state changes; unchanged polls are not repeated.
Exit status is nonzero for terminal partial/failed outcomes and for an
interrupted watch. Ctrl-C stops only local polling: the daemon-side
operation is not cancelled and keeps running, and the command prints the
command to resume. With --json, stdout carries exactly one final document
and progress goes to stderr.
Flags
| Flag |
Description |
--key |
Request key (required) |
--json |
Output as JSON |
gordon apps diff
gordon apps diff APP [--json]
Shows the normalized desired-vs-active diff (added, removed, changed).
gordon apps secrets
Values are accepted via KEY=VALUE arguments (discouraged: shell history) or
stdin. Names must already exist in desired or active state. Only key names are
ever echoed back — never values. Secrets are service-scoped: --service is
required for set and delete, and optional for list where it filters to
one service.
gordon apps secrets list
gordon apps secrets list APP [--service SVC] [--json]
Lists registration metadata for an app's secrets — service, key, name, source,
and presence — never secret values. --service filters to one service.
Flags
| Flag |
Description |
--service |
Filter by service |
--json |
Output as JSON |
JSON Output
[
{"service": "web", "key": "DATABASE_URL", "name": "app_database_url", "source": "desired", "presence": "unknown"}
]
gordon apps secrets set
gordon apps secrets set APP --service SVC KEY=VALUE… [--json]
gordon apps secrets set APP --service SVC --stdin [--json]
gordon apps secrets set APP --service SVC --stdin --key KEY [--json]
Reads values in one of three ways:
KEY=VALUE arguments: the value must be a single line of 1–65536 bytes.--stdin: reads KEY=VALUE lines; blank and whitespace-only lines are
ignored and every non-blank value byte is preserved.--stdin --key KEY: reads one raw value for KEY; a single trailing newline
is stripped and the value must still be a single non-empty line.
--key requires --stdin and cannot be combined with KEY=VALUE arguments.
An empty value is rejected, so KEY= is invalid.
Flags
| Flag |
Description |
--service |
Service the secrets belong to (required) |
--stdin |
Read KEY=VALUE lines, or one raw value with --key |
--key |
Secret key for single-value stdin mode |
--json |
Output as JSON |
JSON Output
{"app": "blog", "service": "web", "keys": ["DATABASE_URL"]}
gordon apps secrets delete
gordon apps secrets delete APP KEY --service SVC [--json]
Deletes the registered value for KEY.
Flags
| Flag |
Description |
--service |
Service the secret belongs to (required) |
--json |
Output as JSON |
gordon apps deploy
gordon apps deploy APP [--revision REV] [--service SVC] [--json]
Activates a revision (default: desired head). Fail-fast across services:
the first failure stops the deploy, successful services are preserved,
later services stay unchanged.
When the daemon accepts the deploy and runs the two phases in the
background (HTTP 202), the command polls the operation journal by key until
it is terminal and prints concise progress only when the operation or step
state changes. It never reissues the mutation. In --json mode stdout
carries one final document and progress goes to stderr. Ctrl-C stops only
local polling (the daemon-side operation keeps running) and prints the
gordon apps operations watch command to resume.
gordon apps restart
gordon apps restart APP [--service SVC] [--json]
Restarts from pinned digests without re-resolution.
gordon apps stop
gordon apps stop APP [--json]
Persists the durable stopped intent and stops exact containers.
All data (volumes, secrets) is preserved. Stopped apps stay stopped
across reboot.
gordon apps start
gordon apps start APP [--json]
Clears the stopped intent and ensures running from active state.
gordon apps remove
gordon apps remove APP [--json]
Withdraws workloads. Volumes and secrets are retained as owned orphans
under the old internal UUID; removing frees the name but never implicitly
attaches retained resources to a new app reusing the name.
There is deliberately no purge: destructive volume deletion requires a
separately accepted destructive-action contract.
gordon apps status
gordon apps status APP [--json]
Shows effective vs observed state per service.
gordon apps logs
gordon apps logs APP [--service SVC] [--follow] [--tail N] [--json]
Streams logs for a service in the app's active deployment. The app name and
--service are the only accepted identity: domains and raw container IDs are
never accepted. --service is required when the app has several services.
Workflow Example
# Push the image first (OCI transfer only)
gordon push myapp --build --remote prod
# Apply the manifest that references the pushed tag
gordon apps apply --file blog.toml --remote prod
# Write secret values for registered names
gordon apps secrets set blog --service web DATABASE_URL=... --remote prod
# Deploy the accepted revision (polls 202 operations to terminal)
gordon apps deploy blog --remote prod
# Resume watching an interrupted or externally started operation
gordon apps operations watch blog --key <operation-key> --remote prod
# Inspect
gordon apps show blog --remote prod
gordon apps status blog --remote prod
source
1# Apps Commands
2
3Validate, persist, inspect, and operate applications.
4
5All mutations are executed by the daemon through the admin API.
6Without a reachable daemon the commands fail with `daemon-unavailable`
7instead of writing locally. Mutations are idempotent: every request carries a
8client-generated key, and the daemon binds that key to the exact request.
9Repeating a key replays the recorded result; reusing it for a different request
10is refused. An interrupted operation is never executed twice, so an ambiguous
11outcome is re-queried by key before any retry (never retry under a fresh
12key). Unknown apps are reported as `app not found` and create no state.
13
14## Local and remote targets
15
16With no `--remote`/`GORDON_REMOTE` selected, commands discover the daemon's
17owner-only administration socket. The CLI checks `$XDG_RUNTIME_DIR/gordon/admin.sock`
18when set, then `/run/user/<uid>/gordon/admin.sock`, then `~/.gordon/run/admin.sock`.
19It accepts only a safe owner-owned socket. This works with `auth.enabled=false`:
20the socket carries no bearer token and grants the `local-owner` principal only
21app administration and app log reads. An explicit remote is authoritative and
22never falls back to the socket.
23See [Local-only Mode](../config/auth.md#local-only-mode).
24
25## gordon apps
26
27### Subcommands
28
29| Subcommand | Description |
30|------------|-------------|
31| `apply` | Validate and persist an app manifest |
32| `operations` | Inspect app operation journals |
33| `list` | List applications |
34| `show` | Show desired and active state for an app |
35| `diff` | Show the normalized desired-vs-active diff |
36| `secrets` | Manage app secret values |
37| `deploy` | Activate an app revision |
38| `restart` | Restart an app from pinned digests |
39| `stop` | Stop an app (preserves all data) |
40| `start` | Start a stopped app from active state |
41| `remove` | Remove app workloads (volumes and secrets are retained) |
42| `status` | Show effective vs observed state for an app |
43| `logs` | Show logs for an app service |
44
45---
46
47## gordon apps apply
48
49```bash
50gordon apps apply --file blog.toml [--dry-run] [--deploy] [--json]
51```
52
53Validates a manifest file and persists it as desired state (or dry-runs).
54With `--deploy`, chains exactly the accepted revision into a deploy after
55persistence succeeds; the two outcomes are reported separately because a
56deploy may fail after the apply succeeded.
57
58When the daemon accepts the deploy asynchronously (HTTP 202), the command
59reuses the same by-key watch as `gordon apps deploy`: it polls the
60operation journal until terminal, prints progress only when the operation
61or step state changes, and never reissues the deploy. A terminal
62`partial`/`failed` deploy exits nonzero while still reporting the
63successful apply. Ctrl-C stops only local polling: the daemon-side
64operation keeps running and the command prints how to resume it.
65
66With `--json`, stdout carries exactly one final combined document after the
67deploy reaches a terminal state:
68
69```json
70{
71 "apply": { "app": "blog", "resulting_revision": "rev-b", "pending": true },
72 "deploy": { "op": "op-1", "app": "blog", "status": "success", "outcome": "success" }
73}
74```
75
76No initial running document is emitted, and progress, transient warnings,
77and Ctrl-C resume guidance go to stderr.
78
79`--dry-run` and `--deploy` cannot be combined.
80
81---
82
83## gordon apps list
84
85```bash
86gordon apps list [--json]
87```
88
89Lists applications with one row per app. States are `applied` when no revision is active, `pending` when desired state awaits activation, `stopped` when stopped intent is set, and otherwise `active`. A non-success last operation is appended to `active` in parentheses.
90
91---
92
93## gordon apps show
94
95```bash
96gordon apps show APP [--json]
97```
98
99Shows desired revision and acceptance status, pending state, per-service
100effective revision, container, digest, and restart safety, the resources the
101app owns (volumes, secret paths, image references — never secret values),
102stopped intent, and the last operation with its outcome.
103
104---
105
106## gordon apps operations show
107
108```bash
109gordon apps operations show APP --key KEY [--json]
110```
111
112Recovers one operation journal entry by its client-generated request key.
113`--key` is required. Use it to re-query an ambiguous mutation outcome before
114retrying: repeating the same key replays the recorded result, while a key
115reused for a different request is refused.
116
117### Flags
118
119| Flag | Description |
120|------|-------------|
121| `--key` | Request key (required) |
122| `--json` | Output as JSON |
123
124---
125
126## gordon apps operations watch
127
128```bash
129gordon apps operations watch APP --key KEY [--json]
130```
131
132Polls the operation journal by request key until the operation reaches a
133terminal state, then renders the terminal journal. It never reissues the
134mutation, so it is the safe way to resume after an interrupted deploy or to
135follow an operation started elsewhere. Progress is printed only when the
136operation or step state changes; unchanged polls are not repeated.
137
138Exit status is nonzero for terminal `partial`/`failed` outcomes and for an
139interrupted watch. Ctrl-C stops only local polling: the daemon-side
140operation is not cancelled and keeps running, and the command prints the
141command to resume. With `--json`, stdout carries exactly one final document
142and progress goes to stderr.
143
144### Flags
145
146| Flag | Description |
147|------|-------------|
148| `--key` | Request key (required) |
149| `--json` | Output as JSON |
150
151---
152
153## gordon apps diff
154
155```bash
156gordon apps diff APP [--json]
157```
158
159Shows the normalized desired-vs-active diff (`added`, `removed`, `changed`).
160
161---
162
163## gordon apps secrets
164
165Values are accepted via `KEY=VALUE` arguments (discouraged: shell history) or
166stdin. Names must already exist in desired or active state. Only key names are
167ever echoed back — never values. Secrets are service-scoped: `--service` is
168required for `set` and `delete`, and optional for `list` where it filters to
169one service.
170
171### gordon apps secrets list
172
173```bash
174gordon apps secrets list APP [--service SVC] [--json]
175```
176
177Lists registration metadata for an app's secrets — service, key, name, source,
178and presence — never secret values. `--service` filters to one service.
179
180#### Flags
181
182| Flag | Description |
183|------|-------------|
184| `--service` | Filter by service |
185| `--json` | Output as JSON |
186
187#### JSON Output
188
189```json
190[
191 {"service": "web", "key": "DATABASE_URL", "name": "app_database_url", "source": "desired", "presence": "unknown"}
192]
193```
194
195### gordon apps secrets set
196
197```bash
198gordon apps secrets set APP --service SVC KEY=VALUE… [--json]
199gordon apps secrets set APP --service SVC --stdin [--json]
200gordon apps secrets set APP --service SVC --stdin --key KEY [--json]
201```
202
203Reads values in one of three ways:
204
205- `KEY=VALUE` arguments: the value must be a single line of 1–65536 bytes.
206- `--stdin`: reads `KEY=VALUE` lines; blank and whitespace-only lines are
207 ignored and every non-blank value byte is preserved.
208- `--stdin --key KEY`: reads one raw value for `KEY`; a single trailing newline
209 is stripped and the value must still be a single non-empty line.
210
211`--key` requires `--stdin` and cannot be combined with `KEY=VALUE` arguments.
212An empty value is rejected, so `KEY=` is invalid.
213
214#### Flags
215
216| Flag | Description |
217|------|-------------|
218| `--service` | Service the secrets belong to (required) |
219| `--stdin` | Read `KEY=VALUE` lines, or one raw value with `--key` |
220| `--key` | Secret key for single-value stdin mode |
221| `--json` | Output as JSON |
222
223#### JSON Output
224
225```json
226{"app": "blog", "service": "web", "keys": ["DATABASE_URL"]}
227```
228
229### gordon apps secrets delete
230
231```bash
232gordon apps secrets delete APP KEY --service SVC [--json]
233```
234
235Deletes the registered value for `KEY`.
236
237#### Flags
238
239| Flag | Description |
240|------|-------------|
241| `--service` | Service the secret belongs to (required) |
242| `--json` | Output as JSON |
243
244---
245
246## gordon apps deploy
247
248```bash
249gordon apps deploy APP [--revision REV] [--service SVC] [--json]
250```
251
252Activates a revision (default: desired head). Fail-fast across services:
253the first failure stops the deploy, successful services are preserved,
254later services stay unchanged.
255
256When the daemon accepts the deploy and runs the two phases in the
257background (HTTP 202), the command polls the operation journal by key until
258it is terminal and prints concise progress only when the operation or step
259state changes. It never reissues the mutation. In `--json` mode stdout
260carries one final document and progress goes to stderr. Ctrl-C stops only
261local polling (the daemon-side operation keeps running) and prints the
262`gordon apps operations watch` command to resume.
263
264---
265
266## gordon apps restart
267
268```bash
269gordon apps restart APP [--service SVC] [--json]
270```
271
272Restarts from pinned digests without re-resolution.
273
274---
275
276## gordon apps stop
277
278```bash
279gordon apps stop APP [--json]
280```
281
282Persists the durable stopped intent and stops exact containers.
283All data (volumes, secrets) is preserved. Stopped apps stay stopped
284across reboot.
285
286---
287
288## gordon apps start
289
290```bash
291gordon apps start APP [--json]
292```
293
294Clears the stopped intent and ensures running from active state.
295
296---
297
298## gordon apps remove
299
300```bash
301gordon apps remove APP [--json]
302```
303
304Withdraws workloads. Volumes and secrets are retained as owned orphans
305under the old internal UUID; removing frees the name but never implicitly
306attaches retained resources to a new app reusing the name.
307
308There is deliberately no `purge`: destructive volume deletion requires a
309separately accepted destructive-action contract.
310
311---
312
313## gordon apps status
314
315```bash
316gordon apps status APP [--json]
317```
318
319Shows effective vs observed state per service.
320
321---
322
323## gordon apps logs
324
325```bash
326gordon apps logs APP [--service SVC] [--follow] [--tail N] [--json]
327```
328
329Streams logs for a service in the app's active deployment. The app name and
330`--service` are the only accepted identity: domains and raw container IDs are
331never accepted. `--service` is required when the app has several services.
332
333---
334
335## Workflow Example
336
337```bash
338# Push the image first (OCI transfer only)
339gordon push myapp --build --remote prod
340
341# Apply the manifest that references the pushed tag
342gordon apps apply --file blog.toml --remote prod
343
344# Write secret values for registered names
345gordon apps secrets set blog --service web DATABASE_URL=... --remote prod
346
347# Deploy the accepted revision (polls 202 operations to terminal)
348gordon apps deploy blog --remote prod
349
350# Resume watching an interrupted or externally started operation
351gordon apps operations watch blog --key <operation-key> --remote prod
352
353# Inspect
354gordon apps show blog --remote prod
355gordon apps status blog --remote prod
356```
357
358## Related
359
360- [CLI Overview](./index.md)
361- [Push Command](./push.md)
362- [Deployment](../deployment/index.md)