1# Backup Command
2
3Manage backups for database attachments.
4
5## gordon backups
6
7```bash
8gordon backups <subcommand>
9```
10
11Subcommands:
12
13- `list [domain]` - List backups globally or for one domain
14- `run <domain> [--db <name>]` - Trigger an immediate backup
15- `detect <domain>` - Detect supported databases for a domain
16- `status` - Show backup status across domains
17
18> Backup commands work both locally and remotely.
19>
20> - Local mode (no `--remote`) executes backups through in-process services.
21> - Remote mode uses the admin API on the target instance.
22>
23> `gordon backups run <domain>` auto-selects the database only when exactly one supported DB attachment is detected. If multiple DB attachments are present, pass `--db <name>`.
24
25In normal usage, configure remotes once (`gordon remotes ...`) and run backup commands without per-command remote flags.
26
27## Examples
28
29```bash
30# List all backups
31gordon backups list
32gordon backups list --json
33
34# List backups for one domain
35gordon backups list app.example.com
36
37# Trigger backup (auto-detect when exactly one DB attachment exists)
38gordon backups run app.example.com
39
40# Trigger backup for specific attachment name
41gordon backups run app.example.com --db postgres
42
43# Detect DB attachments
44gordon backups detect app.example.com
45
46# Status summary
47gordon backups status
48```
49
50## JSON Output
51
52`gordon backups list` supports `--json` for machine-readable output.
53
54```bash
55gordon backups list --json
56```
57
58```json
59[
60  {
61    "domain": "app.example.com",
62    "db": "postgres",
63    "status": "completed",
64    "started_at": "2026-03-13T09:45:00Z",
65    "backup_id": "backup_20260313_094500"
66  }
67]
68```
69
70## Output Columns
71
72### list
73
74```text
75<domain>\t<db>\t<status>\t<started_at>\t<backup_id>
76```
77
78### detect
79
80```text
81<name>\t<type>\t<host>\t<port>\t<image>
82```
83
84### status
85
86```text
87<domain>\t<db>\t<status>\t<started_at>
88```
89
90### run
91
92```text
93<domain>\t<db>\t<status>\t<started_at>\t<backup_id>\t<size_bytes>
94```
95
96## Required Permissions
97
98- Read operations (`list`, `status`, `detect`) require `admin:status:read`.
99- `run` requires `admin:config:write`.
100
101## Related
102
103- [CLI Commands](./index.md)
104- [Backups Configuration](../config/backups.md)