CLI Meets Network: Publish, Fetch, and Status Commands

2026-02-15

Until now the CLI operated in isolation: create a tessera, verify it, export it, +list what you have. Everything stayed on your machine. With this release, tes +gains three commands that bridge the gap between local storage and the P2P +network — publish, fetch, and status — by talking to a running tesd over +a Unix socket.

What was built

tesseras-rpc crate — A new shared crate that both the CLI and daemon +depend on. It defines the RPC protocol using MessagePack serialization with +length-prefixed framing (4-byte big-endian size header, 64 MiB max). Three +request types (Publish, Fetch, Status) and their corresponding responses. +A sync DaemonClient handles the Unix socket connection with configurable +timeouts. The protocol is deliberately simple — one request, one response, +connection closed — to keep the implementation auditable.

tes publish <hash> — Publishes a tessera to the network. Accepts full +hashes or short prefixes (e.g., tes publish a1b2), which are resolved against +the local database. The daemon reads all tessera files from storage, packs them +into a single MessagePack buffer, and hands them to the replication engine. +Small tesseras (< 4 MB) are replicated as a single fragment; larger ones go +through Reed-Solomon erasure coding. Output shows the short hash and fragment +count:

Published tessera 9f2c4a1b (24 fragments created)
+Distribution in progress — use `tes status 9f2c4a1b` to track.
+

tes fetch <hash> — Retrieves a tessera from the network using its full +content hash. The daemon collects locally available fragments, reconstructs the +original data via erasure decoding if needed, unpacks the files, and stores them +in the content-addressable store. Returns the number of memories and total size +fetched.

tes status <hash> — Displays the replication health of a tessera. The +output maps directly to the replication engine's internal health model:

+ + + + + +

State	Meaning
Local	Not yet published — exists only on your machine
Publishing	Fragments being distributed, critical redundancy
Replicated	Distributed but below target redundancy
Healthy	Full redundancy achieved

Daemon RPC listener — The daemon now binds a Unix socket (default: +$XDG_RUNTIME_DIR/tesseras/daemon.sock) with proper directory permissions +(0700), stale socket cleanup, and graceful shutdown. Each connection is handled +in a Tokio task — the listener converts the async stream to sync I/O for the +framing layer, dispatches to the RPC handler, and writes the response back.

Pack/unpack in tesseras-core — A small module that serializes a list of +file entries (path + data) into a single MessagePack buffer and back. This is +the bridge between the tessera's directory structure and the replication +engine's opaque byte blobs.

Architecture decisions

Unix socket over TCP: RPC between CLI and daemon happens on the same +machine. Unix sockets are faster, don't need port allocation, and filesystem +permissions provide access control without TLS.
MessagePack over JSON: the same wire format used everywhere else in +Tesseras. Compact, schema-less, and already a workspace dependency. A typical +publish request/response round-trip is under 200 bytes.
Sync client, async daemon: the DaemonClient uses blocking I/O because +the CLI doesn't need concurrency — it sends one request and waits. The daemon +listener is async (Tokio) to handle multiple connections. The framing layer +works with any Read/Write impl, bridging both worlds.
Hash prefix resolution on the client side: publish and status resolve +short prefixes locally before sending the full hash to the daemon. This keeps +the daemon stateless — it doesn't need access to the CLI's database.
Default data directory alignment: the CLI default changed from +~/.tesseras to ~/.local/share/tesseras (via dirs::data_dir()) to match +the daemon. A migration hint is printed when legacy data is detected.

What comes next

DHT peer count: the status command currently reports 0 peers — wiring +the actual peer count from the DHT is the next step
tes show: display the contents of a tessera (memories, metadata) without +exporting
Streaming fetch: for large tesseras, stream fragments as they arrive +rather than waiting for all of them

+ +