fileup 2.1.0
Share files with a single command
Requires Python: >=3.10

# fileup - Share files with a single command

[![PyPI](https://img.shields.io/pypi/v/fileup.svg)](https://pypi.python.org/pypi/fileup)
[![Build Status](https://github.com/basnijholt/fileup/actions/workflows/pytest.yml/badge.svg)](https://github.com/basnijholt/fileup/actions/workflows/pytest.yml)
[![CodeCov](https://codecov.io/gh/basnijholt/fileup/branch/main/graph/badge.svg)](https://codecov.io/gh/basnijholt/fileup)
[![Documentation](https://img.shields.io/badge/docs-fileup.nijho.lt-blue)](https://fileup.nijho.lt)

<!-- SECTION:intro:START -->
<img src="https://raw.githubusercontent.com/basnijholt/fileup/main/docs/assets/logo.svg" alt="fileup Logo" align="right" style="width: 150px;" />

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

> [!TIP]
> Just call `fu myfile.txt` to upload it and get the URL in your clipboard!
<!-- SECTION:intro:END -->

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Features](#features)
- [Why fileup?](#why-fileup)
- [Installation](#installation)
- [Configuration](#configuration)
  - [FTP Configuration](#ftp-configuration)
  - [SCP Configuration](#scp-configuration)
- [Usage](#usage)
  - [Special Features](#special-features)
- [macOS Integration](#macos-integration)
- [Limitations](#limitations)
- [Support](#support)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SECTION:features:START -->
## Features

- :outbox_tray: Upload via FTP or SCP (using SSH config)
- :clipboard: Upload directly from clipboard (`--clipboard`)
- :alarm_clock: Automatic file expiration and cleanup
- :link: Smart URLs: Jupyter notebooks -> nbviewer, image markdown, direct links
- :clipboard: Automatic URL copy to clipboard (macOS)
- :zap: Simple config using `~/.config/fileup/config.ini`
- :closed_lock_with_key: Supports SSH keys and password authentication
- :feather: Zero dependencies - uses Python standard library
- :scroll: Works as a [single script](https://github.com/basnijholt/fileup/blob/main/fileup.py) or installed package
- :snake: Supports Python >=3.10
<!-- SECTION:features:END -->

<!-- SECTION:why:START -->
## 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.
<!-- SECTION:why:END -->

<!-- SECTION:installation:START -->
## Installation

To install `fileup`, simply run the following command:

```bash
pip install -U fileup
```
or use `uv` or `pipx`:
```bash
uv tool install fileup
pipx install fileup
```
<!-- SECTION:installation:END -->

<!-- SECTION:configuration:START -->
## 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:

```ini
# ~/.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 =

```
<!-- SECTION:configuration:END -->

<!-- SECTION:ftp-config:START -->
### FTP Configuration
For FTP uploads, you need to provide both `username` and `password` in the `[ftp]` section.
<!-- SECTION:ftp-config:END -->

<!-- SECTION:scp-config:START -->
### 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
<!-- SECTION:scp-config:END -->

## Usage

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

In a nutshell, you can use `fileup` by running:
```bash
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:
```bash
# 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`:
<!-- CODE:BASH:START -->
<!-- echo '```bash' -->
<!-- fu -h -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```bash
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).
```

<!-- OUTPUT:END -->

<!-- SECTION:special-features:START -->
### Special Features

- **Jupyter Notebooks**: If you're uploading a Jupyter notebook (`.ipynb`), the returned URL will be accessible via [nbviewer.jupyter.org](http://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
<!-- SECTION:special-features:END -->

<!-- SECTION:macos:START -->
## 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`
<!-- SECTION:macos:END -->

<!-- SECTION:limitations:START -->
## 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
<!-- SECTION:limitations:END -->

<!-- SECTION:support:START -->
## 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](https://github.com/basnijholt/fileup/issues). We also welcome pull requests for bug fixes or new features.

Happy sharing! :rocket:
<!-- SECTION:support:END -->

---

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