joecalsend/README.md

# JocalSend, a TUI [LocalSend](https://github.com/localsend/localsend) implementation

LocalSend is, in its 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." It
comes in the form a Flutter/Dart cross-platform GUI application that runs on both mobile and desktop
devices. Using it on mobile is very nice, but the desktop experience is a bit lacking in zazz.

JocalSend is an implementation of the [LocalSend protocol](https://github.com/localsend/protocol)
that uses [Ratatui](https://github.com/ratatui/ratatui) to provide an interactive terminal-based
application, and is compatible with the official app.

Install with `cargo install jocalsend` (requires [Rust](https://rustup.rs/)); tested on Linux, it
will probably work on Macs but if you're on a Mac, you probably have AirDrop. It's also available in
nixpkgs, and so if you're a NixOS user, `nix-shell -p jocalsend` will do what you expect.

## BLOG POSTS!
 - [Announcement post](https://proclamations.nebcorp-hias.com/sundries/jocalsend/)
 - [Design and development](https://proclamations.nebcorp-hias.com/rnd/jocalsend-development/)

## Capabilities and screenshots

As with the official app, JocalSend can be used to send and receive files and text from other
LocalSend instances on your local subnetwork. Most of the modes have the following keybindings
available:

 - `M` -> go back to the main screen
 - `S` -> go to the sending screen, defaulting to sending files
 - `R` -> go to the receiving screen to approve or deny incoming transfers
 - `L` -> go to the logging screen where you can adjust the log level
 - `C` -> clear the list of local peers and re-discover them
 - `H` or `?` -> go to help screen
 - `ESC` -> go back to the previous screen
 - `Q` -> exit the application

When in the sending screen, the following are available

 - `TAB` -> switch between content selection and peer selection
 - `T` -> enter text directly to send, `ESC` to cancel
 - `/` -> fuzzy filename search, use `ESC` to stop inputting text

When in the receiving screen, use `A` to approve the incoming transfer request, or `D` to deny it.

Finally, it will also accept commandline arguments to pre-select a file or pre-populate text to
send:

```
$ jocalsend -h
A terminal implementation of the LocalSend protocol

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
```

### Sending Files

JocalSend has a file-picking widget for selecting files to send:

![sending a file via selection](./media/sending_file.png)

but there's no preview available on the receiving side:

![receiving a file on the mobile app](./media/receiving_file_from_jocalsend.png)

### Sending text

JocalSend supports entering text directly:

![entering text to send](./media/sending_text.png)

and on the receiving side in the official app, you see

![receiving text in the official app](./media/receiving_text_on_phone.png)

### Receiving files

The main screen shows incoming transfer requests:

![incoming transfer request in main screen](./media/main_screen_receiving.png)

hit `r` to enter the "receiving" screen to approve or deny:

![incoming transfer request management screen](./media/receiving_file_receiving_screen.png)

### Receiving text

If the incoming transfer request is plain text, JocalSend will show a preview in both the main
screen and in the receiving screen:

![receiving text with preview in the main screen](./media/receiving_text_main_screen.png)

![receiving text with preview in the receiving screen](./media/receiving_text_receive_screen.png)

## Thanks

 - to the LocalSend developers for the app and protocol
 - to [wyli](https://github.com/wylited) for the initial [protocol backend](https://github.com/wylited/localsend) implementation

[![Built With Ratatui](https://ratatui.rs/built-with-ratatui/badge.svg)](https://ratatui.rs/)