Skip to content

README.md

Latest commit

 

History

History
175 lines (124 loc) · 8 KB

README.md

File metadata and controls

175 lines (124 loc) · 8 KB

Catbox Uploader

Catbox Catbox Uploader for Windows

Version Chat Download License

A Windows-based context menu tool to upload files to Catbox.moe and Litterbox.catbox.moe with a slick GUI progress bar, thumbnail previews, upload history, and options to upload anonymously or with a saved userhash.

🚀 Features

  • ✅ Right-click Context Menu Integration for quick uploads and automatically copy the URL to clipboard
  • 🧾 Upload History Viewer storing all the uploads in a local SQL DB with thumbnails and status, marking deleted files and expired links in red-strikedthrough text, now also supports search in v1.1.7
  • 🗑 Delete files from Catbox user data right from the history window
  • 👤 Userhash Authentication (optional)
  • 🕵️‍♂️ Anonymous Upload Mode
  • ⏳ Litterbox Support (1h, 12h, 24h, 72h expiration)
  • 📊 Live Progress Bar with file thumbnails
  • 🖼️ Generates thumbnails for images, videos, and common file types

🧩 Installation

✅ 1. Download or Build

  • Download the latest Windows Installer Package from the releases tab
  • Or build it yourself using PyInstaller:

  1. Clone the repo and open the terminal inside the installation directory using:

    git clone https://github.com/karimawi/CatboxUploader

  2. Install the required dependencies

    pip install -r requirements.txt

  3. Build using PyInstaller:

pyinstaller --noconfirm --onedir --windowed --icon ".\icons\icon.ico" --add-data ".\icons;icons" --add-data ".\unins.vbs;." ".\catbox.py"

📂 2. Run Once to Setup Context Menu

When you run the program for the first time with no arguments, It will add context menu entries for Catbox and Litterbox in the registry

🖱️ Usage

Right-click any file and choose one of the options: Context Menu Options

📤 Catbox Menu

  • Upload as User – Uses your saved userhash
  • Upload Anonymously – No login needed
  • Edit Userhash – Set or update your Catbox userhash
  • Upload History – View a list of previous uploads with links and thumbnails

⌛ Litterbox Menu

  • Upload with expiration times:
    • 1h, 12h, 24h, 72h

🔧 Command-Line Options

You can also run from the command line:

catbox.exe [--anonymous] [--litterbox {1h,12h,24h,72h}] <file>
Option Description
<file> File to upload
--anonymous Upload without userhash
--litterbox Upload with expiry (Litterbox)
--edit-userhash Prompt to enter a new userhash
--history Show upload history GUI

Upload Demo

📁 Upload History

Each upload is logged with:

  • 🔗 Link to uploaded file
  • 🖼️ Thumbnail (for media types)
  • 📅 Timestamp
  • 📄 Clickable local file path (opens file in default app when clicked)
  • 🗂️ Right-click file path menu with "Copy Path", "Open File", and "Show in Folder" options
  • 🗑️ Supports deleting the file from Catbox for user uploaded files
  • ❌ Supports bulk select and remove from history with select mode
  • 🗑️ Mass delete selected files from Catbox with live progress tracking
  • 🎬 Right-click context menu for video URLs with embeddable link option

Upload History

🔐 Where is the userhash stored?

It's saved securely under:

HKEY_CURRENT_USER\Software\CatboxUploader

Use --edit-userhash anytime to update it via a GUI prompt.

🎥 Demo

Demo Video ⚠ Outdated

💡 Tips

  • Run catbox.exe with no arguments to re-register or update context menu
  • You can safely delete and re-run to reset registry entries
  • Upload history helps you keep track of everything you've uploaded with no retention
  • You can bulk upload if you select more than one file, the program will launch multiple instances for each file
  • You might struggle with SSL or Timeout error when uploading large files, this is due to the Catbox's API limitiations, it cannot keep an open connection for such long periods of time if you don't have fast enough internet to upload your file

📃 TODO

  • Make the file paths in the history window clickable to open the file in the default app ✅ Implemented clickable file paths
  • Right-click path context menu, add an option to view file in folder ✅ Added file context menu with "Show in Folder" option
  • Include minutes and hours in ETA calculations ✅ Enhanced ETA display with hours, minutes, and seconds
  • Fix copying invalid blob ✅ Fixed clipboard copying
  • Implement a button to copy an embeddable URL to enable video preview with Benny's Embed Generator for apps like Discord ✅ Added right-click context menu for video embeds
  • Mass delete functionality ✅ Added mass delete with progress tracking
  • Add retry option for failed uploads

🐾 Credits

Catbox API by Catbox.moe ❤️ Support them here https://catbox.moe/support.php

📜 License

GNU General Public License v3.0