jocalsend post

content/sundries/jocalsend/index.md

@@ -0,0 +1,170 @@
++++
+title = "Jocalsend: actually useful software if you're a weirdo like me"
+slug = "jocalsend"
+date = "2025-08-21"
+[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 you `$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 if 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 all pretty much there is!
+
+## Wrapping up
+
+Anyway, it's been pretty 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 to 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).