<p align="center"> <img src="data/logo.svg" alt="miniserve - a CLI tool to serve files and dirs over HTTP"><br> </p>

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

Set a custom index file to serve instead of a file listing:

miniserve --index test.html

Serve an SPA (Single Page Application) so that non-existent paths are forwarded to the SPA's router instead

miniserve --spa --index index.html

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/

Require username/password from file (separate logins with new lines):

miniserve --auth-file auth.txt 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

Insert custom headers

miniserve --header "Cache-Control:no-cache" --header "X-Custom-Header:custom-value" -p 8080 /tmp/myshare
# Check headers in another terminal
curl -I http://localhost:8080

If a header is already set or previously inserted, it will not be overwritten.

Start with TLS:

miniserve --tls-cert my.cert --tls-key my.key /tmp/myshare
# Fullchain TLS and HTTP Strict Transport Security (HSTS)
miniserve --tls-cert fullchain.pem --tls-key my.key --header "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload" /tmp/myshare

If the parameter value has spaces, be sure to wrap it in quotes. (To achieve an A+ rating at https://www.ssllabs.com/ssltest/, enabling both fullchain TLS and HSTS is necessary.)

Upload a file using curl:

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

(where $FILE is the path to the file. This uses miniserve's default port of 8080)

Note that for uploading, we have to use -- to disambiguate the argument to -u. This is because -u can also take a path (or multiple). If a path argument to -u is given, uploading will only be possible to the provided paths as opposed to every path.

Another effect of this is that you can't just combine flags like this -uv when -u is used. In this example, you'd need to use -u -v.

Create a directory using curl:

# in one terminal
miniserve --upload-files --mkdir .
# in another terminal
curl -F "mkdir=$DIR_NAME" http://localhost:8080/upload\?path=\/

(where $DIR_NAME is the name of the directory. This uses miniserve's default port of 8080.)

Use the raw renderer for use with simple viewers

You can pass ?raw=true with requests where you only require minimal HTML output for CLI-based browsers such as lynx or w3m. This is enabled by default without any extra flags:

miniserve .
curl http://localhost:8080?raw=true

You can enable a convenient copy-pastable footer for wget using --show-wget-footer:

miniserve --show-wget-footer .

Afterwards, check the bottom of any rendered page. It'll have a neat wget command you can easily copy-paste to recursively grab the current directory.

Take pictures and upload them from smartphones:

miniserve -u -m image -q

This uses the --media-type option, which sends a hint for the expected media type to the browser. Some mobile browsers like Firefox on Android will offer to open the camera app when seeing this.

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
• Directory creation
• Pretty themes (with light and dark theme support)
• Scan QR code for quick access
• Shell completions
• Sane and secure defaults
• TLS (for supported architectures)
• Supports README.md rendering like on GitHub
• Range requests
• WebDAV support
• Healthcheck route (at /__miniserve_internal/healthcheck)

Usage

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

Usage: miniserve [OPTIONS] [PATH]

Arguments:
  [PATH]
          Which path to serve

          [env: MINISERVE_PATH=]

Options:
  -v, --verbose
          Be verbose, includes emitting access logs

          [env: MINISERVE_VERBOSE=]

      --index <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.

          [env: MINISERVE_INDEX=]

      --spa
          Activate SPA (Single Page Application) mode

          This will cause the file given by --index to be served for all non-existing file paths. In effect,
          this will serve the index file whenever a 404 would otherwise occur in order to allow the SPA
          router to handle the request instead.

          [env: MINISERVE_SPA=]

      --pretty-urls
          Activate Pretty URLs mode

          This will cause the server to serve the equivalent `.html` file indicated by the path.

          `/about` will try to find `about.html` and serve it.

          [env: MINISERVE_PRETTY_URLS=]

  -p, --port <PORT>
          Port to use

          [env: MINISERVE_PORT=]
          [default: 8080]

  -i, --interfaces <INTERFACES>
          Interface to listen on

          [env: MINISERVE_INTERFACE=]

  -a, --auth <AUTH>
          Set authentication

          Currently supported formats:
          username:password, username:sha256:hash, username:sha512:hash
          (e.g. joe:123, joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)

          [env: MINISERVE_AUTH=]

      --auth-file <AUTH_FILE>
          Read authentication values from a file

          Example file content:

          joe:123
          bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
          bill:

          [env: MINISERVE_AUTH_FILE=]

      --route-prefix <ROUTE_PREFIX>
          Use a specific route prefix

          [env: MINISERVE_ROUTE_PREFIX=]

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

          [env: MINISERVE_RANDOM_ROUTE=]

      --file-external-url <FILE_BASE_URL>
          Optional external URL (e.g., 'http://external.example.com:8081') prepended to file links in listings.
          Allows serving files from a different URL than the browsing instance. Useful for setups like:
          one authenticated instance for browsing, linking files (via this option) to a second,
          non-indexed (-I) instance for direct downloads. This obscures the full file list on
          the download server, while users can still copy direct file URLs for sharing.
          The external URL is put verbatim in front of the relative location of the file, including the protocol.
          The user should take care this results in a valid URL, no further checks are being done.

          [env: MINISERVE_FILE_EXTERNAL_URL=]

  -P, --no-symlinks
          Hide symlinks in listing and prevent them from being followed

          [env: MINISERVE_NO_SYMLINKS=]

  -H, --hidden
          Show hidden files

          [env: MINISERVE_HIDDEN=]

  -S, --default-sorting-method <DEFAULT_SORTING_METHOD>
          Default sorting method for file list

          [env: MINISERVE_DEFAULT_SORTING_METHOD=]
          [default: name]

          Possible values:
          - name: Sort by name
          - size: Sort by size
          - date: Sort by last modification date (natural sort: follows alphanumerical order)

  -O, --default-sorting-order <DEFAULT_SORTING_ORDER>
          Default sorting order for file list

          [env: MINISERVE_DEFAULT_SORTING_ORDER=]
          [default: desc]

          Possible values:
          - asc:  Ascending order
          - desc: Descending order

  -c, --color-scheme <COLOR_SCHEME>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME=]
          [default: squirrel]
          [possible values: squirrel, archlinux, zenburn, monokai]

  -d, --color-scheme-dark <COLOR_SCHEME_DARK>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME_DARK=]
          [default: archlinux]
          [possible values: