Tempserv - Docs & CLI Reference

📁

Max file

100 MB

⏱️

Expiry

1min–24hr

🔐

Password

File mode only

🌐

Site mode

Always public

📋

Paste API

Pre-create URLs

👁

AutoWatch

Live monitor

📦

Compress

HTML/CSS/JS

🔄

Sync

One command

💡 Storage: Files up to 20 MB are stored in Cloudflare KV. Larger files (up to 100 MB) use external temporary storage — handled transparently, no configuration needed.

Why Use the CLI?

BENEFITS

🔑 Auto Token Management

The CLI automatically saves your access tokens to ~/.tempserv/config.json after every upload. No need to manually copy or store tokens — sync, replace, and delete commands find the right token for you.

🔄 One-Command Sync

Made local changes? tempserv sync ./folder pushes only what changed. Same URL, same expiry, zero hassle.

📦 Compress Before Upload

--compress flag minifies HTML, CSS, and JS automatically. Smaller files = faster loads.

📊 Diff & Compare

tempserv diff ./folder slug shows exactly what's different between your local files and the live deployment.

🚀 CI/CD Ready

Scriptable, JSON output, no browser needed. Perfect for GitHub Actions, cron jobs, and automated pipelines.

🌐 Web UI is Also Available!

Prefer a visual interface? Visit tempserv.badman993944.workers.dev for:

Drag & Drop — Drop entire folders directly onto the page
Click to Upload — Select files or folders from your device
Live Preview — See your site instantly after upload
One-Click Copy — URL and token copied to clipboard
Quick Actions — Open, Replace, or Delete from the browser

💡 CLI is recommended for developers. Web UI is great for quick uploads and non-technical users.

CLI Commands

TERMINAL

🌐 Site Deployment

tempserv site ./folderDeploy static site

tempserv site ./f -e 24hrCustom expiry

tempserv site ./f --compressMinify before upload

tempserv sync ./folderSync changes to live

tempserv sync ./f -cSync + compress

tempserv sync ./f -s slug -t tokManual override

⚠ Sites are always public — password not supported

📤 File Upload

tempserv upload file.zipUpload single file

tempserv upload ./site --mode siteUpload folder

tempserv upload f.pdf -p passPassword protect

tempserv upload f.mp4 -e 6hrCustom expiry

tempserv download abc123Download file

tempserv info abc123View file info

tempserv replace abc new.txtReplace a file

🛠️ Utilities

tempserv open abc123Open in browser

tempserv open ./folderOpen folder's deploy

tempserv statusWorker health check

tempserv share abc123Get shareable link

tempserv share abc --copyCopy link clipboard

tempserv diff ./f abc123Compare local vs server

tempserv listShow recent uploads

⚙️ Management

tempserv delete abc123Delete a resource

tempserv clean --expired-onlyRemove expired records

tempserv clean --allClear all records

tempserv login [url]Set instance URL

tempserv --json listJSON output

tempserv --json statusJSON health check

tempserv --url http://... upload fOverride base URL

📋 Paste & Watch

tempserv pasteCreate paste URL

tempserv paste -e 6hrCustom expiry

tempserv paste-write SLUG "text"Append text

tempserv paste-write SLUG "t" -a clean&addClear then write

tempserv paste-write SLUG -a cleanClear all text

tempserv autowatch SLUGWatch for 5min

tempserv autowatch SLUG -d 120 -i 32min, 3s interval

Quick Start

# Install
pip install --upgrade tempserv-cli

# Deploy a website in one command
tempserv site ./my-website --compress
# → https://tempserv.badman993944.workers.dev/site/a7x9k2

# Make changes locally, then sync
tempserv sync ./my-website
# → Site updated, same URL, same expiry ✅

# Open it in your browser
tempserv open ./my-website

# Share the link
tempserv share --copy

Why Use the REST API?

BENEFITS

🚫 No Installation

Zero dependencies. Just curl, wget, or any HTTP client. Works on any machine — servers, phones (Termux), containers, GitHub Actions, cron jobs.

📜 Script Everything

Upload, replace, delete, and query files from bash scripts, Python, Node.js, or any language. Full automation without installing anything.

🔧 Universal Compatibility

Works with Postman, Insomnia, httpie, fetch API, axios, requests — any tool that speaks HTTP. No SDK or library required.

⚡ Direct & Raw

Full control over every parameter. Bypass the CLI entirely — send multipart forms, set custom headers, handle responses your way.

🌍 Language Agnostic

Use it from Python, Node.js, Go, Rust, PHP, Java — literally any language with HTTP support. No bindings, no wrappers.

📝 Quick Examples

# Upload a file with curl — no install needed
curl -X POST https://tempserv.badman993944.workers.dev/api/upload \
  -F "mode=file" \
  -F "expiry=6hr" \
  -F 'paths=["report.pdf"]' \
  -F "files=@report.pdf"

# Bash script — upload & get link in one line
RESP=$(curl -s -X POST https://tempserv.badman993944.workers.dev/api/upload   -F "mode=file" -F "expiry=1hr"   -F 'paths=["backup.tar.gz"]' -F "files=@backup.tar.gz")
URL=$(echo $RESP | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
echo "Uploaded: $URL"

REST API Reference

ENDPOINTS

POST /api/upload

Upload a file or website. Returns URL, access token, and expiry info.

Field	Type	Description
`mode`	string	site or file
`expiry`	string	Preset: `15min` `30min` `1hr` `2hr` `6hr` `12hr` `24hr` — or custom `1`–`1440` minutes
`paths`	JSON array	File paths: `["index.html","css/style.css"]`
`files`	File(s)	Multipart file data
`password`	string	Optional password protection (file mode only)

# Upload a single file
curl -X POST https://tempserv.badman993944.workers.dev/api/upload \
  -F "mode=file" \
  -F "expiry=1hr" \
  -F 'paths=["myfile.zip"]' \
  -F "files=@myfile.zip"

# Upload a website
curl -X POST https://tempserv.badman993944.workers.dev/api/upload \
  -F "mode=site" \
  -F "expiry=2hr" \
  -F 'paths=["index.html","css/style.css","js/app.js"]' \
  -F "files=@index.html" \
  -F "files=@css/style.css" \
  -F "files=@js/app.js"

# Response 201
{
  "url": "https://tempserv.badman993944.workers.dev/site/a7x9k2",
  "slug": "a7x9k2",
  "accessToken": "1cFhS",
  "expiresAt": 1776771331,
  "expiresIn": 3600,
  "mode": "site",
  "protected": false
}

GET /api/info/{slug}

Get JSON metadata about a deployment including all files, sizes, and MIME types.

# Response 200
{
  "slug": "a7x9k2",
  "type": "site",
  "expires_at": 1776771331,
  "files": [
    { "path": "index.html", "size": 420, "mime_type": "text/html" },
    { "path": "style.css", "size": 128, "mime_type": "text/css" }
  ],
  "total_files": 2,
  "total_size": 548
}

GET /site/{slug}

Serves index.html with cookie-based asset routing. Redirects to /site/{slug}/ and sets a 30-minute session cookie.

GET /site/{slug}/{path}

Serves sub-files (CSS, JS, images, etc.) with correct MIME types.

https://tempserv.badman993944.workers.dev/site/a7x9k2           → index.html
https://tempserv.badman993944.workers.dev/site/a7x9k2/style.css  → CSS file
https://tempserv.badman993944.workers.dev/site/a7x9k2/app.js    → JavaScript

GET /file/{slug}

File info page with download & preview buttons. Password gate if protected.

GET /file/{slug}/dl

Direct download with Content-Disposition: attachment. Supports ?pw=password for protected files.

GET /file/{slug}/view

Inline preview for browser-viewable types (images, PDFs, videos, text).

PUT /api/{slug}

Replace files at the same URL. Old files are deleted, new ones go live. Expiry preserved.

Header	Value
`X-Access-Token`	Your access token

curl -X PUT https://tempserv.badman993944.workers.dev/api/a7x9k2 \
  -H "X-Access-Token: 1cFhS" \
  -F 'paths=["index.html","style.css"]' \
  -F "files=@index.html" \
  -F "files=@style.css"

# Response 200
{ "success": true, "message": "Resource replaced.", "slug": "a7x9k2" }

DELETE /api/{slug}

Permanently delete a resource and all its files from KV + D1.

Header	Value
`X-Access-Token`	Your access token

curl -X DELETE https://tempserv.badman993944.workers.dev/api/a7x9k2 \
  -H "X-Access-Token: 1cFhS"

# Response 200
{ "success": true, "message": "Resource deleted." }

POST /api/file-auth/{slug}

Verify password for a protected file. Returns {"ok":true} or {"ok":false}.

curl -X POST https://tempserv.badman993944.workers.dev/api/file-auth/a7x9k2 \
  -H "Content-Type: application/json" \
  -d '{"password":"mypass"}'

POST /api/paste

Create an empty paste with a pre-allocated URL. Write text later via the write API. Perfect for CI/CD pipelines — get the URL first, push logs as they arrive.

Field	Type	Description
`expiry`	string	Preset or custom minutes (same as upload)

# Create a paste
curl -X POST https://tempserv.badman993944.workers.dev/api/paste \
  -H "Content-Type: application/json" \
  -d '{"expiry":"1hr"}'

# Response 201
{
  "url": "https://tempserv.badman993944.workers.dev/paste/x8k2m",
  "slug": "x8k2m",
  "accessToken": "R2AwO",
  "writeUrl": "https://tempserv.badman993944.workers.dev/api/paste/x8k2m",
  "expiresIn": 3600
}

POST /api/paste/{slug}

Write text to an existing paste. Supports multiple actions. Rate limited to 20 requests per minute per IP.

Field	Type	Description
`text`	string	Text to write (not required for `clean` action)
`action`	string	append (default) \| replace \| clean \| clean&add

# Append text (default)
curl -X POST https://tempserv.badman993944.workers.dev/api/paste/x8k2m \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: R2AwO" \
  -d '{"text":"Build started...","action":"append"}'

# Replace all content
curl -X POST ... -d '{"text":"Fresh data","action":"replace"}'

# Clear all text
curl -X POST ... -d '{"action":"clean"}'

# Clear then write new text
curl -X POST ... -d '{"text":"New beginning!","action":"clean&add"}'

GET /paste/{slug}

HTML view of the paste with copy button and API hint.

GET /paste/{slug}/raw

Plain text content of the paste. Perfect for scripting.

curl https://tempserv.badman993944.workers.dev/paste/x8k2m/raw

Error Codes

Status	Meaning
400	Bad request — invalid mode, expiry, missing files
401	Missing `X-Access-Token` header
403	Invalid access token or wrong password
404	Resource not found
410	Resource expired — auto-deleted
429	Rate limit exceeded (paste API: 20 req/min)

URL Structure

Pattern	Purpose	Auth
`/site/{slug}`	Website hosting	Cookie 30min
`/site/{slug}/{path}`	Site sub-files	Cookie
`/file/{slug}`	File info page	None
`/file/{slug}/dl`	Direct download	?pw= if protected
`/file/{slug}/view`	Inline preview	?pw= if protected
`/paste/{slug}`	Paste HTML view	Public
`/paste/{slug}/raw`	Paste raw text	Public
`/{asset}`	Cookie fallback	Reads cookie

Tempserv CLI — pypi.org/project/tempserv-cli

Built with Cloudflare Workers + KV + D1

Tempserv CLI & API