Headless App

Fastest check — role, base, data, peers

No op required. The service rewrites a status file every few seconds; read it (or run the status subcommand) to see the role, which base it is on / replicating, whether it joined, the live peer count, item count and quota.

# over SSH on the peer
cat ~/listam-data/headless-status.json
# …or the CLI (exits 1 when the status is stale = not running)
node headless.mjs status --storage ~/listam-data

{
  "role": "participant",         # participant = full writer · blind-storage = ciphertext mirror
  "mode": "secure-store",
  "baseId": "fnv1a32:42fc0b1b",  # the project base this peer is on / replicating
  "joined": true,                # joined another base vs. owns its own
  "peerCount": 1,                # live replication connections right now
  "itemCount": 30,               # items in the materialised list
  "inviteActive": false,
  "quota": { "usedBytes": 4462636, "maxBytes": 1073741824, "exceeded": false },
  "startedAt": 1782399966987, "updatedAt": 1782416867419
}

A blind-storage peer reports pins[] instead — the cores it mirrors, each a fingerprint + length — and states "encryptionKey":"never-held": it holds ciphertext only.

Live ops — FIFO in, journal out

The peer reads JSON ops from stdin, which the installer wires to <storage>/control.fifo (held open read-write so it never hits EOF — an EOF means shutdown). Replies print to stdout, which systemd routes to the journal. So you echo an op into the FIFO and read the reply from the journal, matched by id.

# terminal A — watch replies
journalctl --user -u listam-headless -f

# terminal B — send ops (one JSON object per line)
echo '{"id":1,"op":"status"}'            > ~/listam-data/control.fifo
echo '{"id":2,"op":"add","text":"milk"}' > ~/listam-data/control.fifo
echo '{"id":3,"op":"dump"}'              > ~/listam-data/control.fifo

# → appears in terminal A:
# {"id":2,"ok":true}
# {"id":3,"ok":true,"items":[…],"peerCount":1,"joined":true,"roster":[…]}

Not under systemd? Run it in the foreground and ops/replies are just stdin/stdout: node headless.mjs run --storage ~/listam-data, then type the JSON lines.

Recipes

# What role / base / data is this peer on?
cat ~/listam-data/headless-status.json

# Full item list + the owner-signed writer roster (who can write)
echo '{"id":1,"op":"dump"}'    > ~/listam-data/control.fifo
echo '{"id":2,"op":"members"}' > ~/listam-data/control.fifo

# Add / tick / edit / delete an item   (itemId comes from a dump)
echo '{"id":3,"op":"add","text":"buy bread"}'                       > ~/listam-data/control.fifo
echo '{"id":4,"op":"done","itemId":"abc123","isDone":true}'         > ~/listam-data/control.fifo
echo '{"id":5,"op":"edit","itemId":"abc123","text":"buy 2 loaves"}' > ~/listam-data/control.fifo
echo '{"id":6,"op":"delete","itemId":"abc123"}'                     > ~/listam-data/control.fifo

# Mint an invite for another device to join THIS base   (reply: {"inviteKey":"…z32…"})
echo '{"id":7,"op":"invite"}' > ~/listam-data/control.fifo

# Join another peer's whole base (REPLACES this peer's base; 180s budget)
echo '{"id":8,"op":"join","invite":"PASTE_Z32"}' > ~/listam-data/control.fifo

# Share / join a SINGLE list (additive — the rest of the project stays private)
echo '{"id":9,"op":"share-list","listId":"default"}'      > ~/listam-data/control.fifo
echo '{"id":10,"op":"join-list","invite":"PASTE_Z32"}'    > ~/listam-data/control.fifo

# Back up / restore (plain JSON dump, id-stable upsert on import)
echo '{"id":11,"op":"export","path":"/home/cassandrina/listam-export.json"}' > ~/listam-data/control.fifo
echo '{"id":12,"op":"import","path":"/home/cassandrina/listam-export.json"}' > ~/listam-data/control.fifo

# Pre-join encrypted auto-backups
echo '{"id":13,"op":"set-backup-password","password":"hunter2"}' > ~/listam-data/control.fifo
echo '{"id":14,"op":"list-backups"}'                             > ~/listam-data/control.fifo
echo '{"id":15,"op":"restore-backup","file":"NAME","password":"hunter2"}' > ~/listam-data/control.fifo

# Graceful stop   (or: systemctl --user stop listam-headless)
echo '{"id":16,"op":"shutdown"}' > ~/listam-data/control.fifo

CLI subcommands

Every op

Aliases: print-invite→invite, dump-list→dump, add-item→add, edit-item→edit, mark-done→done, delete-item→delete.