+++
title = "Jocalsend: actually useful software if you're a weirdo like me"
slug = "jocalsend"
date = "2025-08-22"
updated = "2025-08-23"
[taxonomies]
tags = ["software", "sundry", "proclamation", "localfirst", "useful", "p2p"]
+++

# Jocalsend: a peer-to-peer file sharing program using local IP subnetworking

Recently, I released a program called
[`jocalsend`](https://git.kittencollective.com/nebkor/joecalsend), which is a play on
"[LocalSend](https://localsend.org/)". LocalSend is, in its own words, "a free,
open-source app that allows you to securely share files and messages with nearby devices over your
local network without needing an internet connection." You can think of it as a sort of "we have
[AirDrop](https://en.wikipedia.org/wiki/AirDrop) at home", where "home" is non-Apple devices and
computers. I happen to be a person without any Apple devices, and basically the only thing I ever
envy about those unlike me is AirDrop, since I often want to transfer files or bits of text back and
forth between my phone and computer.

LocalSend comes in the form of a cross-platform graphical app that runs on both mobile and desktop.
On my Android phone, it works great, and does exactly what I'd hope it would do. On my Linux
desktop, however, it requires a lot more fiddly mousing than I like to do, plus launching a GUI for
what's supposed to be a low-friction, ad-hoc sharing activity is, frankly, a drag. I've always been
a fan of terminal-based programs, and the terminal has been my primary interface for many, many
years. It seemed natural to write a TUI version of LocalSend, and so here we are.

## So, what's it good for?

Has this ever happened to you? Someone sends you a text message on your phone, and it contains a
URL. You go to check it out, but it looks completely terrible on mobile, or tries to force you to
install an app, or whatever; you want to use your desktop or laptop computer to look at it. But now
what? Send yourself an email? Paste it into a Google Doc? Maybe you have Signal desktop so you can
send yourself a Signal message then read it there. Or maybe you have an image or something on your
desktop computer that you'd like to get onto your phone; your choices are basically the same as with
a bit of text.

You know what all those choices have in common? They all *fucking suck ass*. Primarily because they
require a round-trip from your local network out to a corporate data center, which means you need to
be connected to the public internet. What if your internet connection is down? Well, maybe you'd be
able to do something with your phone, but that means you might want to get things from your regular
computer to the phone, which you can't do now. But they're also all just kinda obnoxious,
aesthetically. It would be nice to just be able to directly beam the data from one thing to another,
and that's what LocalSend does[^airdrop-explained].

Something else that's nice about LocalSend is that they published [a protocol
spec](https://github.com/localsend/protocol), which means that anyone can make their own compatible
implementation, which is where jocalsend comes in. I plan on writing a follow-up[^follow-up]
about the design and implementation of jocalsend, but that's going to be a much longer and
even-more-niche-interest post, so I'll just skip that for now. Stay tuned, though, if that's a
boat-floater for ya!

## How do I install it?

### Via cargo

Jocalsend is written in [Rust](https://www.rust-lang.org/), a programming language released by
Mozilla about ten years ago, and meant to be used for writing high-performance software in a way
that was easier to do safely than in other languages like C++, but [its aegis has
expanded](https://doc.rust-lang.org/book/foreword.html) to encompass basically any and all types of
software. Installing Rust on your computer is [very simple](https://rustup.rs/).

One nice thing that Rust provides out of the box is a package manager called "cargo"[^cargo], and I
think this fact alone is responsible for a big portion of Rust's success and popularity. You can use
cargo to install any published Rust package that's on [crates.io](https://crates.io), the official
Rust package site. Jocalsend has been [published to crates.io](https://crates.io/crates/jocalsend),
so if you have Rust installed, just run,

```
cargo install jocalsend
```

which will install the `jocalsend` program to `$HOME/.cargo/bin`; add that directory to your `$PATH`
and then you can run `jocalsend` from the command line:

```
$ jocalsend -h
A TUI for LocalSend

Usage: jocalsend [OPTIONS]

Options:
  -f, --file <FILE>  File to pre-select for sending
  -t, --text <TEXT>  Text string to send
  -h, --help         Print help
  -V, --version      Print version
```

### From nixpkgs

If you use [NixOS](https://nixos.org/) or otherwise use nixpkgs[^nixpkgs], you can also get it from there:

```
nix-shell -p jocalsend
```

and it'll do what you expect.

## How do I use it?

When you first run it, you'll be on the main screen. Clockwise from the bottom, the lower left contains information about the
network it's on, the lower right has a list of any LocalSend peers it discovered, the upper right
has log output from jocalsend, and finally the upper left will show any incoming transfer requests,
with possible text preview:

![main screen](./main_screen.png)

Here we can see that my phone is already available as a peer.

### Receiving files and text

I can use my phone to send some text to my computer, and it will show a preview of the text even in
the main screen:

![main screen receiving text](./main_screen_txt_rx_request.png)

If I hit `r`, I'll be taken to the receiving screen, where I can approve or deny the incoming
transfer request, with `a` or `d` respectively:

![receiving screen, with text preview](./receiving_text_from_phone.png)

If the incoming content is not plain text, no preview will be shown:

![receiving screen, no preview](./receiving_file_from_phone.png)

From nearly any screen, hitting the `esc` key will take you to whatever screen you were in
previously.

### Sending files and text

Hitting the `s` key will take you to the sending screen. By default, it will show a list of files
from your current directory in the upper left, with log output on the right, and peers on the
bottom:

![sending files with arrow-based picking](./picking_file_sending.png)

Hit `/` to do fuzzy filename selection by entering text:

![sending files with fuzzy filename selection](./fuzzy_file_sending.png)

Regardless of whether or not you're doing fuzzy filename search, the up and down arrow keys will
move the selection up or down, respectively.

If you'd like to send text, hit `t`:

![sending text](./sending_text_to_phone.png)

then `enter` to send, and you can see a preview on the mobile device:

![receiving text on the mobile app](./receiving_text_on_phone.png)

And that's pretty much all there is!

## Wrapping up

Anyway, I've had fun making jocalsend. I now use it daily, and every time I do, I'm pretty
darned pleased with myself. If you're a weirdo like me who doesn't use Apple stuff, maybe this would
be useful for you, too.

---

[^airdrop-explained]: did I just mansplain why something like airdrop is useful? idunno, maybe, sorry

[^follow-up]: still need to write part 2 of [my Gossip Glomers](/sundries/glome-ing-pt1) post...

[^cargo]: I honestly don't really get the naming theme with Rust, cargo, and crates; are crates typically rusty? I usually think of them as being made of wood.

[^nixpkgs]: I wasn't the one who added it to nixpkgs; a total stranger who is a nixpkgs maintainer saw that it had been featured
    as the ["terminal tool of the week"](https://terminaltrove.com/jocalsend/) on a site called
    Terminal Trove, thought it was neat, and [added it](https://github.com/NixOS/nixpkgs/pull/435106).
