diff --git a/content/sundries/jocalsend/fuzzy_file_sending.png b/content/sundries/jocalsend/fuzzy_file_sending.png new file mode 100644 index 0000000..6cfc35d Binary files /dev/null and b/content/sundries/jocalsend/fuzzy_file_sending.png differ diff --git a/content/sundries/jocalsend/index.md b/content/sundries/jocalsend/index.md new file mode 100644 index 0000000..ead3b70 --- /dev/null +++ b/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 to pre-select for sending + -t, --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). diff --git a/content/sundries/jocalsend/main_screen.png b/content/sundries/jocalsend/main_screen.png new file mode 100644 index 0000000..79aa584 Binary files /dev/null and b/content/sundries/jocalsend/main_screen.png differ diff --git a/content/sundries/jocalsend/main_screen_txt_rx_request.png b/content/sundries/jocalsend/main_screen_txt_rx_request.png new file mode 100644 index 0000000..dc379ce Binary files /dev/null and b/content/sundries/jocalsend/main_screen_txt_rx_request.png differ diff --git a/content/sundries/jocalsend/picking_file_sending.png b/content/sundries/jocalsend/picking_file_sending.png new file mode 100644 index 0000000..1432d0e Binary files /dev/null and b/content/sundries/jocalsend/picking_file_sending.png differ diff --git a/content/sundries/jocalsend/receiving_file_from_phone.png b/content/sundries/jocalsend/receiving_file_from_phone.png new file mode 100644 index 0000000..deda47b Binary files /dev/null and b/content/sundries/jocalsend/receiving_file_from_phone.png differ diff --git a/content/sundries/jocalsend/receiving_text_from_phone.png b/content/sundries/jocalsend/receiving_text_from_phone.png new file mode 100644 index 0000000..878200d Binary files /dev/null and b/content/sundries/jocalsend/receiving_text_from_phone.png differ diff --git a/content/sundries/jocalsend/receiving_text_on_phone.png b/content/sundries/jocalsend/receiving_text_on_phone.png new file mode 100644 index 0000000..dc0e0be Binary files /dev/null and b/content/sundries/jocalsend/receiving_text_on_phone.png differ diff --git a/content/sundries/jocalsend/sending_text_to_phone.png b/content/sundries/jocalsend/sending_text_to_phone.png new file mode 100644 index 0000000..d86a19d Binary files /dev/null and b/content/sundries/jocalsend/sending_text_to_phone.png differ