fileup - Share files with a single command

fileup is your go-to Python package for hassle-free uploading and sharing of files right from your command-line interface. You can set a time limit after which the file will be automatically removed, ensuring the security of your data.

Table of Contents

• Features
• Why fileup?
• Installation
• Configuration
  • FTP Configuration
  • SCP Configuration
• Usage
  • Special Features
• macOS Integration
• Limitations
• Support

Features

• 📤 Upload via FTP or SCP (using SSH config)
• 📋 Upload directly from clipboard (--clipboard)
• ⏰ Automatic file expiration and cleanup
• 🔗 Smart URLs: Jupyter notebooks -> nbviewer, image markdown, direct links
• 📋 Automatic URL copy to clipboard (macOS)
• ⚡ Simple config using ~/.config/fileup/config.ini
• 🔐 Supports SSH keys and password authentication
• 🪶 Zero dependencies - uses Python standard library
• 📜 Works as a single script or installed package
• 🐍 Supports Python >=3.10

Why fileup?

I frequently need to share files quickly with colleagues or friends. Whether it's a screenshot, a code snippet, or a Jupyter notebook, I wanted a tool that:

1. Works from the command line with minimal typing
2. Automatically copies the URL to my clipboard
3. Supports automatic expiration for temporary files
4. Requires no external dependencies

fileup was born out of this need - a simple, focused tool that does one thing well.

Installation

To install fileup, simply run the following command:

pip install -U fileup

or use uv or pipx:

uv tool install fileup
pipx install fileup

Configuration

Before you can start sharing your files, you'll need to create a configuration file at ~/.config/fileup/config.ini with the following structure:

# ~/.config/fileup/config.ini
[default]
protocol = ftp  # or scp
hostname = example.com  # or the Host from your ~/.ssh/config
base_folder = /path/to/files  # where files are stored on the server
file_up_folder =  # subdirectory in URL, can be empty
url = files.example.com  # the actual URL where files are accessible

[ftp]
username = my_user_name
password = my_difficult_password

[scp]
# If empty, will use your SSH config
username =
# If using SSH config, no need for these
private_key =
password =

FTP Configuration

For FTP uploads, you need to provide both username and password in the [ftp] section.

SCP Configuration

For SCP uploads, you have two options:

1. Use your SSH config by setting protocol = scp and using a hostname from your ~/.ssh/config
2. Explicitly configure SCP by providing username and optionally private_key in the [scp] section

Usage

For a list of available commands, type fu -h.

In a nutshell, you can use fileup by running:

fu [filename]

The command supports several options:

• -t DAYS, --time DAYS: Set an expiration time in days (default: 90, use 0 for no expiration)
• -d, --direct: Return a direct URL without any prefixes
• -i, --img: Return the URL formatted for markdown image embedding
• -c, --clipboard: Upload image/text currently in your clipboard (image preferred)

Examples:

# Regular file upload
fu image.png

# Upload from clipboard with an auto-generated name
fu --clipboard

# Upload from clipboard with an explicit remote filename
fu --clipboard screenshot.png

This is the output of fu -h:

usage: fu [-h] [-t TIME] [-d] [-i] [-c] [filename]

Publish a file.

Create a config file at ~/.config/fileup/config.ini with the following structure:

[default]
protocol = ftp  # or scp
hostname = example.com  # or the Host from your ~/.ssh/config
base_folder = /path/to/files  # where files are stored on the server
file_up_folder =  # subdirectory in URL, can be empty
url = files.example.com  # the actual URL where files are accessible

[ftp]
username = my_user_name
password = my_difficult_password

[scp]
# If empty, will use your SSH config
username =
# If using SSH config, no need for these
private_key =
password =

positional arguments:
  filename         Local filename. With --clipboard this is an optional remote filename.

options:
  -h, --help       show this help message and exit
  -t, --time TIME  If time is 0 the file will never be deleted, default is 90 days.
  -d, --direct
  -i, --img
  -c, --clipboard  Upload clipboard content (image preferred, then text).

Special Features

• Jupyter Notebooks: If you're uploading a Jupyter notebook (.ipynb), the returned URL will be accessible via nbviewer.jupyter.org
• Automatic Deletion: Files with expiration times are automatically removed when their time is up
• Clipboard Upload: Upload clipboard image/text with fu --clipboard
• URL Copying: On macOS, the URL is automatically copied to your clipboard

macOS Integration

fileup uses pbcopy so the uploaded URL is automatically copied on macOS. For clipboard uploads, it will try common commands in order:

• image: pngpaste, wl-paste, xclip
• text: pbpaste, wl-paste, xclip, xsel, powershell

Limitations

• Automatic URL-to-clipboard copy currently uses macOS pbcopy
• Clipboard image uploads need a compatible command (e.g. pngpaste on macOS)
• FTP passwords are stored in plain text; use with caution
• SCP implementation requires the ssh and scp commands to be available

Support

We appreciate your feedback and contributions! If you encounter any issues or have suggestions for improvements, please file an issue on the GitHub repository. We also welcome pull requests for bug fixes or new features.

Happy sharing! 🚀

Give fileup a try today and experience the convenience of effortless file sharing right from your command-line!