miniserve - a CLI tool to serve files and dirs over HTTP

For when you really just want to serve some files over HTTP right now!

miniserve is a small, self-contained cross-platform CLI tool that allows you to just grab the binary and serve some file(s) via HTTP. Sometimes this is just a more practical and quick way than doing things properly.

Screenshot

How to use

Serve a directory:

miniserve linux-distro-collection/

Serve a single file:

miniserve linux-distro.iso

Require username/password:

miniserve --auth joe:123 unreleased-linux-distros/

Require username/password as hash:

pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/

Generate random 6-hexdigit URL:

miniserve -i 192.168.0.1 --random-route /tmp
# Serving path /private/tmp at http://192.168.0.1/c789b6

Bind to multiple interfaces:

miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare

Upload a file using

curl

:

# in one terminal
miniserve -u .
# in another terminal
curl -F "[email protected]$FILE" http://localhost:8080/upload\?path\=/

(where

$FILE

Features

• Easy to use
• Just works: Correct MIME types handling out of the box
• Single binary drop-in with no extra dependencies required
• Authentication support with username and password (and hashed password)
• Mega fast and highly parallel (thanks to Rust and Actix)
• Folder download (compressed on the fly as

  .tar.gz

  or

  .zip

  )
• File uploading
• Pretty themes (with light and dark theme support)
• Scan QR code for quick access
• Shell completions
• Sane and secure defaults

Usage

miniserve 0.13.0
Sven-Hendrik Haase , Boastful Squirrel 
For when you really just want to serve some files over HTTP right now!

USAGE:
    miniserve [FLAGS] [OPTIONS] [--] [PATH]
FLAGS:
    -D, --dirs-first
            List directories first
-r, --enable-tar
        Enable tar archive generation

-z, --enable-zip
        Enable zip archive generation

        WARNING: Zipping large directories can result in out-of-memory exception because zip generation is done in
        memory and cannot be sent on the fly
-u, --upload-files
        Enable file uploading

-h, --help
        Prints help information

-P, --no-symlinks
        Do not follow symbolic links

-o, --overwrite-files
        Enable overriding existing files during file upload

-q, --qrcode
        Enable QR code display

    --random-route
        Generate a random 6-hexdigit route

-V, --version
        Prints version information

-v, --verbose
        Be verbose, includes emitting access logs
OPTIONS:
    -a, --auth ...
            Set authentication. Currently supported formats: username:password, username:sha256:hash,
            username:sha512:hash (e.g. joe:123,
            joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)
    -c, --color-scheme 
            Default color scheme [default: squirrel]  [possible values: squirrel, archlinux,
            zenburn, monokai]
    -d, --color-scheme-dark 
            Default color scheme [default: archlinux]  [possible values: squirrel, archlinux,
            zenburn, monokai]
        --header 
...
            Set custom header for responses
        --index 
            The name of a directory index file to serve, like "index.html"

        Normally, when miniserve serves a directory, it creates a listing for that directory. However, if a
        directory contains this file, miniserve will serve that file instead.
-i, --interfaces <interfaces>...
        Interface to listen on

-p, --port <port>
        Port to use [default: 8080]

    --print-completions <shell>
        Generate completion file for a shell [possible values: zsh, bash, fish,
        powershell, elvish]
-t, --title <title>
        Shown instead of host in page title and heading
ARGS:
    
            Which path to serve

How to install

On Linux: Download

miniserve-linux

chmod +x miniserve-linux
./miniserve-linux

Alternatively, if you are on Arch Linux, you can do

pacman -S miniserve

On OSX: Download

miniserve-osx

chmod +x miniserve-osx
./miniserve-osx

Alternatively install with Homebrew.

brew install miniserve
miniserve

On Windows: Download

miniserve-win.exe

miniserve-win.exe

With Cargo: Make sure you have a recent version of Rust. Then you can run

cargo install miniserve
miniserve

With Docker: If you prefer using Docker for this, run

docker run -v /tmp:/tmp -p 8080:8080 --rm -it svenstaro/miniserve /tmp

Shell completions

If you'd like to make use of the built-in shell completion support, you need to run

miniserve
--print-completions 

# For bash
miniserve --print-completions bash > ~/.local/share/bash-completion/miniserve
# For zsh
miniserve --print-completions zsh > /usr/local/share/zsh/site-functions/_miniserve
# For fish
miniserve --print-completions fish > ~/.config/fish/completions/miniserve.fish

Binding behavior

For convenience reasons, miniserve will try to bind on all interfaces by default (if no

-i

-i 0.0.0.0

-i ::

-i

Why use this over alternatives?

• darkhttpd: Not easily available on Windows and it's not as easy as download and go.
• Python built-in webserver: Need to have Python installed, it's low performance, and also doesn't do correct MIME type handling in some cases.
• netcat: Not as convenient to use and sending directories is somewhat involved.

Releasing

This is mostly a note for me on how to release this thing:

• Make sure

  CHANGELOG.md

  is up to date.

• cargo release --dry-run 

• cargo release 

• Releases will automatically be deployed by Github Actions.
• Docker images will automatically be built by Docker Hub.
• Update Arch package.