A lightweight Linux CLI tool for serving directories over HTTP. Wraps miniserve or Python's built-in HTTP server with automatic port selection, multi-server management, and optional internet exposure via Cloudflare Tunnel.
Copy the serve-dir script somewhere on your $PATH:
cp serve-dir ~/.local/bin/
chmod +x ~/.local/bin/serve-dirRequired:
- Bash 4.0+
ss(fromiproute2)- At least one backend:
python3(usually pre-installed) orminiserve
Optional:
cloudflared— for--public(internet exposure)qrencode— QR code display for shareable URLsxsel— clipboard integration
serve-dir <directory> [OPTIONS]| Flag | Description |
|---|---|
--port <N> |
Starting port (default: 8000, auto-increments if occupied) |
--lan |
Bind to 0.0.0.0 for local network access |
--public |
Expose to the internet via Cloudflare Tunnel |
--backend miniserve|python |
Choose backend (auto-detects by default) |
serve-dir ./my-files # Serve on localhost:8000
serve-dir ./my-files --port 9000 # Use port 9000 (or next free)
serve-dir ./my-files --lan # Accessible on your LAN
serve-dir ./my-files --public # Expose to the internet
serve-dir ./my-files --backend miniserve # Force miniserve backendserve-dir list # List all running instances
serve-dir stop # Stop a server (or --port <N> to target one)
serve-dir start # Start a stopped server
serve-dir restart # Restart a server
serve-dir status # Check server status
serve-dir uninstall # Stop and remove a serverWhen multiple servers are running, use --port <N> to target a specific one.
Completion scripts are provided for bash, zsh, and fish in the completions/ directory.
Bash — copy to your bash completions directory:
cp completions/serve-dir.bash ~/.local/share/bash-completion/completions/serve-dirZsh — copy to a directory in your $fpath:
cp completions/serve-dir.zsh ~/.zfunc/_serve-dir
# Make sure ~/.zfunc is in fpath (add to ~/.zshrc before compinit):
# fpath=(~/.zfunc $fpath)Fish — copy to fish completions:
cp completions/serve-dir.fish ~/.config/fish/completions/serve-dir.fishserve-dir auto-detects the best available backend:
- miniserve (preferred) — fast Rust-based server with a rich file browser UI
- Python (fallback) — uses
python3 -m http.server, available on most systems
Each server instance gets its own temp directory with control scripts (start, stop, restart, status, uninstall) and config. Instances are tracked in /tmp/serve-dir-instances/<port>, making it easy to manage multiple servers simultaneously.
Port selection starts at 8000 (or the value given with --port) and automatically increments until a free port is found.
./tests/run_all.shRuns ~95 tests across 8 suites covering flag parsing, backend detection, server lifecycle, port discovery, network features, HTTP serving, Cloudflare Tunnel integration, and edge cases.
MIT