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
.zipfile, or more than a measly25MBin 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
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 macOS/Linux, if you are using Homebrew
brew install portal
On Windows, if you are using Scoop
scoop install portal
On Windows, if you are using WinGet
winget install SpatiumPortae.portal
On Arch Linux (AUR)
yay -S portal-bin
On any platform, you can get the latest release manually, or simply run
curl -sL portal.spatiumportae.com | bash
or
wget -qO - portal.spatiumportae.com | bash
How it works
Sending files and folders
To send files:
portal send <file1> <file2> <folder1> <folder2> ...
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
The two clients will establish a connection through a relay server…
How it works
Sending files and folders
To send files:
portal send <file1> <file2> <folder1> <folder2> ...
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
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
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:
bashzshfishpowershell
To see installation instructions for your shell and platform, run:
portal completion [bash|zsh|fish|powershell] --help
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...
...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
boom. supernova.
portal receive 42-relative-parsec-supernova
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
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
The server log output is JSON. Super-recommended to run it through jq!
portal serve --port 1337 2>&1 | jq .
...
{
"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"
}
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)
Really cool.. but I wonder can a "direct transfer" happen outside local network? Or always through server if not in the same network?
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!
Reminds me of Magic Wormhole
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 :)
Oh for sure, definitely see plenty of differences, just first thing I thought of when reading it! 🤘🏼
Thought so too, only that I found MW to be slower when sending larger files. Hopefully this one is better at that.
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 :)
filetransfer.io is way better than Google Drive
Sure, but this is offline file transfer, instead that is online.
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.
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.
Tab-completion for passwords? What could possibly go wrong? ;^)