GitHub - SpatiumPortae/portal: Portal is a quick and easy command-line file tran...
source link: https://github.com/SpatiumPortae/portal
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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 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
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. 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
that 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.
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
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
# The URL of the relay server.
relay: portal.spatiumportae.com
# Log debug output to file.
verbose: false
# Prompt for overwriting duplicates when receiving files.
prompt_overwrite_files: true
# The port used when serving the relay using "portal serve".
relay_serve_port: 8080
# The style of the TUI.
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"
}
More details about the connection process
Technical details
Building from source
The Makefile
has everything you need.
To build a binary containing all commands, run:
PORTAL_VERSION=v1.x.x make build
It's important to include PORTAL_VERSION
, which is a semantic version string. This is needed
in order to validate senders and receivers against the relay, so transfers are disallowed
when on different major versions, for instance.
Maintainers
Acknowledgements
a big thank you to magic-wormhole for greatly inspiring the concept of Portal.
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..
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK