romm-cli 0.33.1

Rust-based CLI and TUI for the ROMM API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# Save sync (`sync` command)

This document covers the one-shot save sync workflow added to `romm-cli` for RomM sync endpoints.

## Server compatibility

`romm-cli sync` uses sync endpoints introduced in RomM `4.9.0-alpha.2` (pre-release), including:

- `POST /api/sync/negotiate`
- `POST /api/sync/sessions/{session_id}/complete`
- `GET /api/sync/sessions`
- `GET /api/sync/sessions/{session_id}`
- `POST /api/sync/devices/{device_id}/push-pull`

It also uses device and save endpoints:

- `POST/GET /api/devices`
- `POST /api/saves`
- `GET /api/saves/{id}/content`

## Command surface

### Device setup

Register an API-mode device:

```bash
romm-cli sync device register --name "My Handheld" --sync-mode api
```

Inspect devices:

```bash
romm-cli sync device list
romm-cli sync device get <device-id>
```

### Plan only

Negotiate operations from a manifest without changing files:

```bash
romm-cli sync plan --device-id <device-id> --manifest ./sync-manifest.json
```

### Execute sync

Run negotiated operations and complete the sync session:

```bash
romm-cli sync run --device-id <device-id> --manifest ./sync-manifest.json
```

Choose conflict behavior:

```bash
romm-cli sync run --device-id <device-id> --manifest ./sync-manifest.json --conflict fail
romm-cli sync run --device-id <device-id> --manifest ./sync-manifest.json --conflict skip
```

`--conflict fail` is the default.

### Sessions and push-pull

```bash
romm-cli sync sessions list
romm-cli sync sessions list --device-id <device-id>
romm-cli sync sessions get <session-id>
romm-cli sync push-pull <device-id>
```

## Manifest format

Manifest file is JSON:

```json
{
  "saves": [
    {
      "rom_id": 123,
      "path": "saves/zelda.srm",
      "file_name": "zelda.srm",
      "slot": null,
      "emulator": "retroarch"
    }
  ]
}
```

Rules:

- `rom_id` and `path` are required.
- `path` may be absolute or relative to the manifest file directory.
- `file_name` is optional; if omitted, the filename from `path` is used.
- `slot` and `emulator` are optional.

## Runtime behavior

`sync plan` and `sync run` both:

1. Read all manifest save files.
2. Compute local metadata per file:
   - `updated_at` (UTC RFC3339)
   - `file_size_bytes`
   - `content_hash`
3. Call `POST /api/sync/negotiate`.

`sync run` then executes operations:

- `upload`: `POST /api/saves` with `rom_id`, `device_id`, and `session_id`.
- `download`: `GET /api/saves/{id}/content` and writes to `--download-dir` (or manifest directory).
- `no_op`: no file change.
- `conflict`: fail or skip based on `--conflict`.

After processing operations, `sync run` always calls:

- `POST /api/sync/sessions/{session_id}/complete`

with `operations_completed` and `operations_failed`.

## Content hash details

To match RomM server behavior:

- normal files: MD5 of file bytes
- zip files: MD5 of a deterministic string built from sorted zip entries as `name:entry_md5`, joined by newlines

This keeps negotiate comparisons consistent for save files that are zip archives.