Send a file

From the app

Open it on both devices, pair once, then tap the device and choose the file. It starts immediately: there is no upload step, because there is nowhere to upload to.

Files of any size. An interrupted transfer resumes where it stopped rather than starting again, because the receiver keeps a map of which chunks it already has.

From a terminal

sparsh send report.pdf --to "Phone"

By name, with no code, because the pairing already happened. Several files at once is several arguments. Exit code 0 means the far side has the bytes on disk and the hash matched, not that they were sent.

To receive:

sparsh receive --into ~/Downloads

Or leave sparsh serve running and the device is simply reachable.

From an agent

sparsh_send(paths: ["/abs/path/report.pdf"], to: "Phone")

It returns when the far side has the file. A path inside the working directory goes straight through. Anything outside asks you first, because reading an arbitrary path and shipping it is exactly what a prompt-injected agent reaches for.

Arrived files come back as paths, never contents:

sparsh_inbox()

Read them with your own file tools. A gigabyte base64'd into a tool result is a context-window fire, not a feature.

What can go wrong

The device is offline. Presence needs a signalling server; on public relays alone there is no device list and the honest answer is an empty one rather than a pretend one.

The pairing predates device keys. The daemon refuses a session it cannot verify rather than accepting a weaker one. Run sparsh invite once and the pairing is upgraded for good.

Both peers are behind a strict NAT. ICE finds a path or falls back to a TURN relay over 443. The relay forwards ciphertext; it cannot read a byte.