lain-upload 1.23

A simple CLI file uploader for multiple file-hosting services, with optional clipboard copy.

lain-upload

A simple CLI file uploader for multiple file-hosting services, with optional clipboard copy.

Installation

Via PyPI (Recommended)

You have the option to choose between the standard version (lain-upload) or the desktop version (lain-upload[clipboard]), which adds clipboard support for auto-copying links.

[!NOTE] For brevity, the examples below use the desktop version.

With pip (Basic)

pip install "lain-upload[clipboard]"

With pipx (Isolated)

pipx install "lain-upload[clipboard]"

With uv (Best)

The most efficient way to install or run the uploader.

# Permanent isolated installation
uv tool install "lain-upload[clipboard]"

# Run once without installing
uvx --with "lain-upload[clipboard]" lain-upload <file1> <file2> <file3>

# Run in scripts or ad-hoc environments
uv run --with "lain-upload[clipboard]" lain-upload <file1> <file2> <file3>

From Source (Development)

# Clone the repository and navigate to it
git clone [e-mail]:NecRaul/lain-upload.git
cd lain-upload

# Install environment and all development dependencies (mandatory and optional)
uv sync --dev

# Install pre-commit hook
uv run pre-commit install

# Optional: Run all linters and type checkers manually
uv run pre-commit run --all-files

# Run the local version
uv run lain-upload <file1> <file2> <file3>

# Run tests
uv run pytest tests

Usage

Simply provide the path to the file or files you wish to upload.

# Upload a single file (default host: catbox)
lain-upload kuroneko.png

# Upload multiple files from different directories
lain-upload /path/to/kuroneko.png /path/to/another/directory/shironeko.png yamineko.png ../kamineko.png

# Select a specific host
lain-upload --host uguu kuroneko.png

# Use host authentication when supported
lain-upload --host mixdrop --auth [e-mail]:generated_api_key kuroneko.png

# Set temporary file expiration when supported (e.g. 1h, 12h, 24h, 72h, etc.)
lain-upload --host litterbox --expire-after 24h kuroneko.png

# Enable longer generated filenames when supported
lain-upload --host 0x0 --long-filenames -- kuroneko.png shironeko.png

# Upload to every available non-deprecated host
lain-upload --host all kamineko.png

# Display help and version
lain-upload -h
lain-upload -v

Supported Hosts

• catbox - Support for user authentication with userhashes.
• litterbox - Support for custom expiration time and longer upload filenames.
• pomf - No extra options (deprecated).
• uguu - No extra options.
• fileditch - No extra options.
• tempditch - No extra options.
• 0x0 - Support for custom expiration time and longer upload filenames.
• gofile - Support for user authentication with bearer API tokens.
• pixeldrain - Support for user authentication with API keys (Required).
• buzzheavier - No extra options.
• mixdrop - Support for user authentication with mail and API keys (Required).
• sharey - Support for custom expiration time.

Configuration

lain-upload supports a JSON configuration file to set a default host and per-host options. You can create a default config, inspect the effective configuration, and override or ignore the config file at runtime.

• Default path
  • Linux/BSD: $XDG_CONFIG_HOME/necraul/lain-upload.json or ~/.config/necraul/lain-upload.json
  • MacOS: ~/Library/Application Support/necraul/lain-upload.json
  • Windows: %APPDATA%/necraul/lain-upload.json
• Basic structure
  • default_host: host used when --host flag is omitted (default: "catbox").
  • hosts: per-host configuration (auth, expire_after, long_filenames, etc.), keyed by host name.

{
  "default_host": "catbox",
  "hosts": {
    "catbox": {
      "auth": null
    },
    "litterbox": {
      "expire_after": "72h",
      "long_filenames": false
    },
    "gofile": {
      "auth": null
    }
  }
}

# Create a default configuration file at the default path
lain-upload --init-config

# Create a default configuration file at a custom path
lain-upload --init-config config.json

# Show the effective configuration (defaults merged with the default config file)
lain-upload --show-config

# Create a default configuration file at the default path and print it
lain-upload --init-config --show-config

# Create a default configuration file at a custom path and print it
lain-upload --init-config /path/to/config.json --show-config

# Show the effective configuration (defaults merged with the custom config file)
lain-upload --config config.json --show-config

# Upload using the config file's default_host (no --host needed)
lain-upload kuroneko.png

# Override the config file's default_host
lain-upload --host uguu shironeko.png

# Use a custom configuration file
lain-upload --config /path/to/config.json kamineko.png

# Ignore the configuration file and use only CLI flags
lain-upload --no-config kuroneko.png

# Override config's host and expiration (CLI flag overrides config)
lain-upload --host litterbox --expire-after 24h kuroneko.png

Dependencies

• requests: send the API request for uploading.
• requests-toolbelt: enable memory-efficient streaming and progress tracking for large uploads.

Optional

• pyperclip: copy the uploaded files' URLs to the clipboard.

How it works

Supported services provide upload endpoints that accept multipart HTTP requests.

This tool automates uploads and adds safety checks and quality-of-life features.

The Manual Way

curl -F "file=@kuroneko.png" https://example-upload-service.tld/upload-endpoint

The lain-upload way

• Batch Processing: Upload multiple files in a single command execution, saving time over individual manual requests.
• Validation: Checks file constraints before uploading (service-specific rules are enforced per host).
• API Request: Sends multipart POST requests via requests and requests-toolbelt, with streaming support for large files.
• Normalization: Parses server responses into clean, shareable URLs.
• Clipboard (Optional): If pyperclip is installed, the result is instantly copied to your clipboard.

Special thanks

• To 7666 of https://lain.la/ for running the pomf service that inspired this project.
• To r/a/dio anons for feedback and suggestions.