tempspace-cli 1.3.0

A command-line tool for uploading files to Tempspace.

🚀 Tempspace

Tempspace is a self-hostable, terminal-themed file sharing service. It allows you to quickly upload files and share them via a link, with features like password protection, one-time downloads, and automatic expiration.

✨ Core Features

• Seamless Uploading: Drag-and-drop web interface, cURL, or a dedicated CLI tool.
• Chunked Uploads: Robust support for large files (default 4GB, configurable) via chunking.
• Security Focused:
  • Password Protection: Secure individual files with a password.
  • One-Time Downloads: Links can be configured to expire after the first download.
  • Rate Limiting: Built-in protection against abuse.
• Efficient Storage: Files with identical content are de-duplicated to save space.
• Flexible Expiration: Set custom expiration times from hours to days.
• Modern UI:
  • Terminal-Inspired Design: A clean, developer-focused interface.
  • QR Code Generation: Instantly generate QR codes for mobile sharing.
  • Local Upload History: Your browser remembers your recent uploads.
• Automatic Cleanup: The server periodically cleans up expired files automatically.

🚀 Getting Started

There are three primary ways to use Tempspace.

1. Web Interface (The Easy Way)

1. Open the service URL (e.g., https://tempspace.fly.dev/ or your self-hosted instance) in your browser.
2. Drag and drop your file(s) or click to browse.
3. Configure options like expiration time, password, or one-time download.
4. Click "Upload" and share the generated link.

2. cURL (From the Terminal)

Use cURL to upload files directly from your command line.

# Basic upload (expires in 24 hours)
curl -F "file=@/path/to/your/file.txt" https://tempspace.fly.dev/upload

# Set a custom expiration time (e.g., 7 days) and password
curl -F "file=@/path/to/secret.txt" \
     -F "hours=168" \
     -F "password=secret123" \
     https://tempspace.fly.dev/upload

# Create a one-time download link
curl -F "file=@/path/to/onetime.zip" \
     -F "one_time=true" \
     https://tempspace.fly.dev/upload

3. Official CLI Tool

For the best terminal experience, install the official CLI tool from PyPI.

Installation

pip install tempspace-cli

Usage

# Interactive mode (prompts for all options)
tempspace --it

# Basic upload (expires in 24 hours)
tempspace /path/to/document.pdf

# Set expiration to 7 days and add a password
tempspace /path/to/archive.zip -t 7d -p "secure_password"

# Display a QR code in the terminal after upload
tempspace /path/to/image.png --qr

# Point to a self-hosted server
tempspace /path/to/file.txt --url http://localhost:8000

🔧 Self-Hosting

You can easily run your own instance of Tempspace using Docker or by running the source code directly.

Method 1: Using Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/Bartixxx32/tempspace.git
   cd tempspace
   

2. Build the Docker image:

   docker build -t tempspace-app .
   

3. Run the container: Create a .env file to configure your admin password.

   cp .env.example .env
   nano .env  # Set your ADMIN_PASS
   

   Then, run the container, mounting the environment file and a volume for persistent storage.

   docker run -d \
     -p 8000:8000 \
     --name tempspace \
     --env-file .env \
     -v $(pwd)/uploads:/app/uploads \
     tempspace-app
   

   Your Tempspace instance will be available at http://localhost:8000.

Method 2: Running from Source

1. Clone the repository:

   git clone https://github.com/Bartixxx32/tempspace.git
   cd tempspace
   

2. Install dependencies: It's recommended to use a virtual environment.

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   pip install -r requirements.txt
   

3. Configure: Copy the example environment file and set your admin password.

   cp .env.example .env
   nano .env
   

4. Run the server:

   python -m uvicorn main:app --host 0.0.0.0 --port 8000
   

⚙️ Configuration (Environment Variables)

Configure your Tempspace instance by creating a .env file in the project root.

Variable	Description	Default
ADMIN_USER	Username for accessing debug/admin endpoints.	admin
ADMIN_PASS	Required. Password for the admin user. The app will not start without this.	changeme123
MAX_FILE_SIZE	Maximum file size in bytes.	4294967296 (4GB)
RATE_LIMIT_UPLOADS	Max uploads per IP per hour.	10
RATE_LIMIT_DOWNLOADS	Max downloads per IP per hour.	100
RATE_LIMIT_WINDOW	The rate limit time window in seconds.	3600 (1 hour)

🛠️ API & Admin Endpoints

• /upload: The primary endpoint for curl and simple POST request uploads.
• /upload/initiate, /upload/chunk, /upload/finalize: Endpoints for the chunked upload flow used by the web UI and CLI.
• /health: A public health check endpoint.
• /debug/stats: (Admin-only) View detailed statistics of all stored files.
• /debug/wipe: (Admin-only) Destructive. Deletes all files and metadata.

Access admin endpoints by providing the admin credentials via HTTP Basic Authentication.

🤝 Contributing

Contributions are welcome! Please fork the repository, make your changes, and submit a pull request.

📝 License

This project is licensed under the MIT License.