resyndeo-files

Read and write files in a Resyndeo fleet share

The Resyndeo fleet file share is a set of files replicated across the user's fleet machines (via Syncthing) — not a local disk, and not the backend database. This skill drives the resyndeo files CLI to list, read, and write those files from any machine.

Every read needs an online machine to serve the bytes; every write lands on an online machine and replicates outward. If no machine is online, reads and writes fail with a clear message — surface that to the user, do not retry forever.

Paths are relative to the share root, forward-slashed (e.g. notes/todo.md).

---

Prerequisites

Before running any command, the user must be:

• Logged in — resyndeo login.
• Have at least one online machine in their Files share.

You do not need to verify these up front; the commands report a clear error if either is missing. See Troubleshooting to map each error to its fix.

---

The three commands

List — resyndeo files ls [path] [--json]

Lists the direct children of a directory in the share (root if path is omitted).

Prefer --json whenever you need to decide things about paths or types programmatically. It prints the raw node array; each node has:

Field	Meaning
path	Full path from the share root
name	Leaf name
is_dir	true for directories
size	Bytes
sync_state	One of synced, syncing, conflict, offline
online	Whether a machine holding this node is currently online
holders	Machines that hold this node

resyndeo files ls                       # list the share root
resyndeo files ls notes --json          # machine-readable listing of notes/

Read — resyndeo files cat <path>

Streams a file's contents to stdout. Internally it asks an online machine to stage the file out and polls until ready, so it may take a few seconds.

resyndeo files cat notes/todo.md

Write — resyndeo files put <path> [localfile]

Whole-file write or overwrite. If localfile is omitted or -, content is read from STDIN. It blocks until the write is confirmed synced back onto an online machine (confirm-ingested), then exits 0. A non-zero exit means it could not confirm the write — treat it as a failure, not a success.

printf '%s' "$content" | resyndeo files put notes/todo.md -   # from stdin
resyndeo files put notes/todo.md /tmp/new-todo.md             # from a local file

---

Editing is read-modify-write

This is a whole-file API — there is no in-place edit. To change a file:

1. resyndeo files cat <path> — fetch the current contents into a temp file.
2. Modify that temp file locally.
3. resyndeo files put <path> <tempfile> — write the full new contents back.

Always stage the contents in a temp file — never capture them in a shell variable. Bash command substitution (var="$(...)") strips every trailing newline, so a round-trip through a variable silently drops a file's final newline on each edit and corrupts plain-text/Markdown files. A temp file preserves the bytes (including the trailing newline) exactly, and is also the only safe path for binary files.

Example

Append a line to notes/todo.md:

# 1. Read current contents into a temp file (exact bytes, trailing newline intact).
resyndeo files cat notes/todo.md > /tmp/todo.md

# 2. Modify the temp file with your normal tools.
printf '%s\n' "- buy milk" >> /tmp/todo.md

# 3. Write the full new contents back (blocks until confirmed synced).
resyndeo files put notes/todo.md /tmp/todo.md

The same pattern handles binary files and large edits — the point is that no shell variable ever holds the file content:

resyndeo files cat data/config.json > /tmp/config.json
# edit /tmp/config.json with your normal tools
resyndeo files put data/config.json /tmp/config.json

Always re-cat before a put if time has passed — another machine may have changed the file since your last read.

---

Troubleshooting

Symptom	What it means	What to tell the user
Auth error / "not logged in"	No valid session	Run resyndeo login, then retry.
"no online machine" on cat/put	Nothing in the share is online to serve or accept bytes	Bring a fleet machine online, then retry. Do not retry in a loop.
put exits non-zero	The write could not be confirmed synced	Report it as a failed write — do not assume the file was saved. Check resyndeo files ls --json and retry once a machine is confirmed online.
ls shows sync_state: conflict	Syncthing has conflicting versions of that node	Warn the user there is a sync conflict on that path; a put may not resolve it cleanly. Let them reconcile on a machine before overwriting.
ls shows sync_state: offline / online: false	The holders of that node are offline	The node exists but cannot be served right now; wait for a holder to come online.

When a command fails for an environmental reason (no machine online, auth), surface the message to the user rather than retrying forever.

---

Fast path (secondary)

If the machine running Claude Code is itself a member of the Files share, the share is just a normal local folder (default ~/resyndeo) that Syncthing keeps in sync. In that case you MAY use the native Read / Edit / Write tools directly on that folder — it is simpler and supports in-place edits.

The resyndeo files commands are the portable, default path: they work from any machine, member or not. When in doubt, use resyndeo files.