DEV Community

Cover image for Portal - a modern file transfer utility šŸŒŒāœØ
Zino Kader
Zino Kader

Posted on • Updated on • Originally published at github.com

 

Portal - a modern file transfer utility šŸŒŒāœØ

Portal

...is a platform-agnostic command-line file transfer utility for sending files from any computer to another.

The year is 2023 and ChatGPT is taking over the world, yet, sending files to each other is still incredibly annoying.

How many times haven't you tried to send a file to a friend through Messenger, WhatsApp, or Discord, just to find out that you cannot send a folder, or a .zip file, or more than a measly 25MB in total?

So... you head over to Google Drive, but then you have to fiddle with the link permissions, and if you're uploading a large file, you have to wait for it to be completely uploaded to Google Drive, before your friend can even start downloading it. Uuuuuugh.

As a developer, you know sending files isn't that hard. So did we, and we got fed up with the current state of things. So we created Portal, a command-line utility to send files quickly and easily.

Installation

See the installation options (curl, brew, yay) on GitHub!
Leave a ā­ if you like it <3

GitHub logo SpatiumPortae / portal

Portal is a quick and easy command-line file transfer utility from any computer to another šŸŒŒ āœØ

Portal

a command-line file transfer utility for sending files from any computer to another

Ā  Ā 

Installation

On any platform, you can get the latest release manually, or simply run:

curl -sL https://portal.spatiumportae.com | bash
Enter fullscreen mode Exit fullscreen mode

or

wget -qO - https://portal.spatiumportae.com | bash
Enter fullscreen mode Exit fullscreen mode

On macOS or Linux, if you are using Homebrew:

brew install SpatiumPortae/homebrew-portal/portal
Enter fullscreen mode Exit fullscreen mode

On Arch Linux (AUR):

yay -S portal-bin
Enter fullscreen mode Exit fullscreen mode

How it works

Sending files and folders

To send files:

portal send <file1> <file2> <folder1> <folder2> ...
Enter fullscreen mode Exit fullscreen mode

The application will output a temporary password on the format 1-inertia-elliptical-celestial

The sender will communicate this password to the receiver over some secure channel.

Receiving files and folders

To receive those files:

portal receive 1-intertia-elliptical-celestial
Enter fullscreen mode Exit fullscreen mode

The two clients will establish a connection through a relay server. The file transfer will then commence with a direct or relayed connection, depending on what's possible.

What it

ā€¦

How it works

Sending files and folders

To send files:

portal send <file1> <file2> <folder1> <folder2> ...
Enter fullscreen mode Exit fullscreen mode

The application will output a temporary password on the format
1-inertia-elliptical-celestial.

The sender will communicate this password to the receiver over some secure channel.

Receiving files and folders

To receive those files:

portal receive 1-intertia-elliptical-celestial
Enter fullscreen mode Exit fullscreen mode

The two clients will establish a connection through a relay server. The file transfer will then commence with a direct or relayed connection, depending on what's possible.

What it looks like āœØ

The sender (top) sends a folder and three files to the receiver (bottom).

In this case, as you can see in the event log, the transfer is made using direct transfer. That means the files are sent directly from one client to the other, no middlemen involved.

As it happens, these computers are in the same local network, and portal recognizes this.

Demo

portal-demo

Features

portal provides:

  • End-to-end encryption using PAKE2
  • Direct transfer of files if possible (e.g. sender and receiver are in the same local network)
  • Fallback to relay server if sender and receiver cannot connect directly
  • Parallel gzip compression of files for faster and more efficient transfers
  • Hosting your own relay (we'd appreciate it if you plan to send a lot of data!)
  • Configurability and shell completions
  • A shiny UI ā­āœØ to gaze your eyes upon while you wait for your files

Completions

portal provides extensive TAB completions for the following shells:

  • bash
  • zsh
  • fish
  • powershell

To see installation instructions for your shell and platform, run:

portal completion [bash|zsh|fish|powershell] --help
Enter fullscreen mode Exit fullscreen mode

Tip!

You probably didn't quite catch the password Bob was screaming across the room.

You can use TAB completions to auto-complete passwords on the receiving end.

Press TAB when entering parts of your password...

portal receive 42-relative-parsec-s...
Enter fullscreen mode Exit fullscreen mode

...and portal will suggest the possible words

$ portal receive 42-relative-parsec-s...

42-relative-parsec-supernova  42-relative-parsec-scatter    42-relative-parsec-solar      42-relative-parsec-spin       42-relative-parsec-static     
42-relative-parsec-sigma      42-relative-parsec-solid      42-relative-parsec-star       42-relative-parsec-storm      42-relative-parsec-system
Enter fullscreen mode Exit fullscreen mode

boom. supernova.

portal receive 42-relative-parsec-supernova
Enter fullscreen mode Exit fullscreen mode

Flags

Receiver

  • -y/--yes: overwrite existing files without [Y/n] prompts

Relay

  • -p/--port: port to host the relay server on

Sender and Receiver

  • -r/--relay: address of the relay server (:8080, myrelay.io:1234, ...)
  • -s/--tui-style: the style of the tui (rich | raw)

Sender, Receiver and Relay

  • -h/--help: output help messages for any command
  • -v/--verbose: log debug info to file

Configuration

portal places its configuration file in $HOME/.config/portal/config.yml.

As evident by the file extension, the config is a simple YAML file with descriptive field names.

Default configuration

relay: portal.spatiumportae.com
verbose: false
prompt_overwrite_files: true
relay_serve_port: 8080
tui_style: rich
Enter fullscreen mode Exit fullscreen mode

Hosting your own relay

The portal binary comes with a built-in relay server.
Spinning up your own relay is as easy as...

portal serve --port 1337
Enter fullscreen mode Exit fullscreen mode

The server log output is JSON. Super-recommended to run it through jq!

portal serve --port 1337 2>&1 | jq .
Enter fullscreen mode Exit fullscreen mode

...

{
  "level": "info",
  "ts": "2023-02-28T02:57:45.310134+01:00",
  "caller": "rendezvous/server.go:77",
  "msg": "serving rendezvous server",
  "version": "v1.2.1",
  "address": ":1337"
}
Enter fullscreen mode Exit fullscreen mode

Maintainers

Acknowledgements

nhooyr/websocket, shollz/pake, charmbracelet/bubbles, charmbracelet/bubbletea, charmbracelet/lipgloss, muesli/reflow, klauspost/pgzip and many, many more.

DigitalOcean <3

A special thanks to our sponsors DigitalOcean.

The public relay available for everyone to use is sponsored by DigitalOcean.

Top comments (12)

Collapse
 
karjkarp profile image
Kary J

Really cool.. but I wonder can a "direct transfer" happen outside local network? Or always through server if not in the same network?

Collapse
 
zinokader profile image
Zino Kader

In our testing, it's mostly in the same local network or within the same NAT at least. Since CG-NAT became a thing, direct connections with TCP has become somewhat impossible. We're looking into UDP hole punching for v2 of Portal, but I'm not very hopeful about it helping all too much. There's always the relay to fall back to, but direct connections are there as a best-effort approach!

Collapse
 
zonaidev profile image
Andrew Reese

Reminds me of Magic Wormhole

Collapse
 
zinokader profile image
Zino Kader

It's very inspired by magic-wormhole! It's a different protocol and all, and has gotten a facelift, but there are other differences too.

We use parallell gzip compression by default, which takes at most a couple of seconds at the start of the transfer if you are sending gigabytes of data, but saves you minutes when sending. Plus, you're busy sending off the password during that time anyway! Then, we're overall sending stuff much faster. Not sure if that's due to inefficiencies in the magic-wormhole protocol, code, or if we just use a faster connection on our relay. We've also made it very straightforward to host your own relay, it's shipped in the client binary.

Side by side, Iā€™m sure you'll find more similarities and differences. I do think there's a place for both, though :)

Collapse
 
zonaidev profile image
Andrew Reese

Oh for sure, definitely see plenty of differences, just first thing I thought of when reading it! šŸ¤˜šŸ¼

Collapse
 
xinnks profile image
James Sinkala

Thought so too, only that I found MW to be slower when sending larger files. Hopefully this one is better at that.

Collapse
 
zinokader profile image
Zino Kader

Do try it out! We don't throttle transfers and have no special treatment for larger files. I bet you should be able to max out your residential internet upload speed :)

Collapse
 
llorx profile image
Jorge Fuentes

filetransfer.io is way better than Google Drive

Collapse
 
leober_ramos33 profile image
Leober Ramos

Sure, but this is offline file transfer, instead that is online.

Collapse
 
zinokader profile image
Zino Kader

That is a good point!

To clarify: if you are hosting your own relay server with Portal, you can transfer files between computers within your local network without any internet access.

Collapse
 
llorx profile image
Jorge Fuentes • Edited

I said "better than Google Drive", not this tool. This post referenced one of the worst file transfer services and I said that there are better options. If you don't mind online but mind Google Drive being a hassle, then go filetransfer.io instead and you'll be good.

Collapse
 
mark_clark_74c4cbc1be06b3 profile image
Mark Clark

Tab-completion for passwords? What could possibly go wrong? ;^)