miniserve(1)

📦 version 0.35.0, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 miniserve(1) 💖

okay so this is the General Commands Manual page for miniserve, bestie. it's giving "tiny http server that ate and left no crumbs" energy and honestly? we're obsessed. here's everything you need, no cap. 🫶

🌸 NAME 🌸

miniserve — for when you really just want to serve some files over HTTP right now! 🎀

like literally. right now. that's the whole vibe. she's not complicated, she's not doing too much, she's just serving. 💅

🌀 SYNOPSIS 🌀

miniserve [-v|--verbose] [--temp-directory] [--index] [--spa] [--quiet]
[--pretty-urls] [-p|--port] [-i|--interfaces] [--workers] [-a|--auth]
[--auth-file] [--route-prefix] [--random-route] [-P|--no-symlinks]
[-H|--hidden] [-S|--default-sorting-method] [-O|--default-sorting-order]
[-c|--color-scheme] [-d|--color-scheme-dark] [-q|--qrcode]
[-u|--upload-files] [--web-upload-files-concurrency] [--chmod]
[--directory-size] [-U|--mkdir] [--pastebin] [-m|--media-type]
[-M|--raw-media-type] [-o|--on-duplicate-files] [-R|--rm-files]
[-r|--enable-tar] [-g|--enable-tar-gz] [-z|--enable-zip]
[-C|--compress-response] [-D|--dirs-first] [-t|--title] [--header]
[-l|--show-symlink-info] [-F|--hide-version-footer]
[--hide-theme-selector] [-W|--show-wget-footer] [--print-completions]
[--print-manpage] [--tls-cert] [--tls-key] [--readme]
[-I|--disable-indexing] [--enable-webdav] [--size-display]
[--file-external-url] [--log-color] [-h|--help] [-V|--version] [PATH]

that's the whole fit check. every single flag, no skips, no "you don't need this one". ✨

💅 DESCRIPTION 💅

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

that's it. that's the mission statement. no thirty-step setup arc, no config file trauma, no main-character-itis from some other server. you point miniserve at a directory (or don't — it'll figure it out, see [PATH] up there 👆) and boom 💥 there's a file listing on the other side. iconic behavior honestly.

like... you could be doing literally anything else with your life and instead you're in a terminal typing one command and now your files have a URL. that's the whole plot twist. 🦋

okay but fr fr, there are a ton of options hiding behind that synopsis, and we're getting into all of them — every flag, every default, every env var, every warning, all of it. nothing gets left on read. 💀

🫶 to be continued... 💖

✨ OPTIONS ✨

okay bestie, this is the big one, the whole menu of vibes you can hand to miniserve. every single flag, no skips, no shortcuts, periodt. 💅

  • -v, --verbose — be loud about what's happening, and yeah that includes spitting out access logs so you can see who's knocking.
  • --temp-directory <TEMP_UPLOAD_DIRECTORY> — where uploaded files get parked before they're moved to their forever home. ngl it's wise to make sure this directory actually writes to disk and not into memory, because surprise, memory is not a filing cabinet.

this value only gets used IF file uploading is turned on. if you don't set it, the OS's default temporary directory gets the job instead.

  • --index <INDEX> — the name of a directory index file to serve, like "index.html".

so normally, when miniserve serves a directory, it just makes a listing for it, cute little browse vibe. but if that directory contains this file, miniserve serves that file instead. slay.

  • --spa — activates SPA (Single Page Application) mode.

this makes the file you gave to --index get served for all non-existing file paths. basically, whenever a 404 would've happened, it serves the index file instead so the SPA router can handle the request itself. the 404 could never. 😌

  • --quiet — less output, and it shushes the warnings. it's giving… silence, on purpose.
  • --pretty-urls — activates Pretty URLs mode.

this makes the server serve the equivalent .html file that the path is pointing at. so:

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

  • -p, --port <PORT> [default: 8080] — the port to use. that's it, that's the whole thing.
  • -i, --interfaces <INTERFACES> — which interface to listen on.
  • --workers <WORKERS> [default: 4] — how many server workers you want grinding. yes bestie, we're working.
  • -a, --auth <AUTH> — set authentication, i.e. put a little lock on the door.

the formats supported rn: username:password, username:sha256:hash, username:sha512:hash. for example: joe:123, joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3. 🔐

  • --auth-file <AUTH_FILE> — read your authentication values from a file instead, so your secrets don't live directly on the command line where everyone can see them.

example file content:

joe:123
bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
bill:

(yes, bill: with nothing after it. that's allowed, we don't judge bill.)

  • --route-prefix <ROUTE_PREFIX> — use a specific route prefix. make it yours. 💖
  • --random-route — generates a random 6-hexdigit route. chaotic, unguessable, iconic.
  • -P, --no-symlinks — hides symlinks from the listing AND prevents them from being followed. they're not invited to this party.
  • -H, --hidden — show hidden files. the ones with the little dot. we see them now. 🫣
  • -S, --default-sorting-method <DEFAULT_SORTING_METHOD> [default: name] — the default way the file list gets sorted.

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: desc] — the default sorting order for the file list.

possible values:

  • asc: ascending order
  • desc: descending order
  • -c, --color-scheme <COLOR_SCHEME> [default: squirrel] — the default color scheme. aesthetic matters, fr fr.

possible values:

  • squirrel
  • archlinux
  • ayu-dark
  • zenburn
  • monokai
  • -d, --color-scheme-dark <COLOR_SCHEME_DARK> [default: archlinux] — default color scheme, but for dark mode hours. 🌙

possible values:

  • squirrel
  • archlinux
  • ayu-dark
  • zenburn
  • monokai
  • -q, --qrcode — enable QR code display, so you can beam the URL to your phone like a lil magical girl. 📱✨
  • -u, --upload-files [<ALLOWED_UPLOAD_DIR>] — enable file uploading, and optionally say which directory people can upload into.

okay important detail: the path you provide here is not a physical file system path. it's relative to the serve dir. for instance, if the serve dir is /home/hello, set this to /upload to allow uploading to /home/hello/upload. and heads up — when you specify it via an environment variable, a path always needs to be specified.

  • --web-upload-files-concurrency <WEB_UPLOAD_CONCURRENCY> [default: 0] — how many uploads can happen at the same time when someone's using the website. you need the upload-files option enabled for this to even matter.

for example, a value of 4 would mean the web browser only uploads 4 files at a time to the web server when using the browser interface.

when the value stays at 0, it attempts to resolve all the uploads at once in the web browser.

NOTE: web pages have a limit on how many active HTTP connections they can make at one time, so even if you set a concurrency limit of 100, the browser might only make progress on the max amount of connections it's allowed to have open for that page. browser said "i have limits bestie". 💀
  • --chmod <CHMOD> — set unix file permissions for uploaded files.

this takes an octal number, for example 0600. by default 0666 & ~umask is used, to simulate the system's default behavior.

  • --directory-size — enable recursive directory size calculation.

this is disabled by default because it's a potentially fairly IO intensive operation. it's giving heavy lifting, so we keep it off unless you ask. 😮‍💨

  • -U, --mkdir — enable creating directories. build your little folder empire.
  • --pastebin — enable creating pastebin 'pastes'.

'pastes' are plaintext files created in the current directory. creating them requires file uploads to be enabled.

  • -m, --media-type <MEDIA_TYPE> — specify which media types are uploadable.

possible values:

  • image
  • audio
  • video
  • -M, --raw-media-type <MEDIA_TYPE_RAW> — directly specify the uploadable media type expression. you're bypassing the vibes and writing the raw thing yourself. respect.
  • -o, --on-duplicate-files <ON_DUPLICATE_FILES> [default: error] — what to do when a file with the same name already exists during upload.

if you enable renaming files, the renaming happens by adding a numerical suffix to the filename before the final extension. for example file.txt will be uploaded as file-1.txt, and the number keeps increasing until an available filename is found. cute, right?

possible values:

  • error
  • overwrite
  • rename
  • -R, --rm-files [<ALLOWED_RM_DIR>] — enable file and directory deletion, and optionally specify which directory that's allowed in. with great power etc etc. ⚠️
  • -r, --enable-tar — enable uncompressed tar archive generation.
  • -g, --enable-tar-gz — enable gz-compressed tar archive generation.
  • -z, --enable-zip — enable zip archive generation.
WARNING: zipping large directories can result in an out-of-memory exception, because zip generation is done in memory and cannot be sent on the fly. so like… small zips only bestie, we're begging. 😭
  • -C, --compress-response — compress the response.
WARNING: enabling this option may slow down transfers due to CPU overhead, so it's disabled by default.

only enable this option if you know your users have slow connections, or if you want to minimize your server's bandwidth usage. otherwise you're just making the CPU do cardio for no reason.

  • -D, --dirs-first — list directories first. folders get the front row seats. 👑
  • -t, --title <TITLE> — shown instead of the host in the page title and heading. rename your whole vibe.
  • --header <HEADER> — inserts custom headers into the responses. specify each header as a 'Header:Value' pair. this parameter can be used multiple times to add multiple headers.

example: --header "Header1:Value1" --header "Header2:Value2" (if a header is already set or was previously inserted, it will not be overwritten.)

  • -l, --show-symlink-info — visualize symlinks in the directory listing. we love a transparent queen. 🦋
  • -F, --hide-version-footer — hide the version footer.
  • --hide-theme-selector — hide the theme selector.
  • -W, --show-wget-footer — if enabled, display a wget command to recursively download the current directory.
  • --print-completions <shell> — generate a completion file for a shell.

possible values:

  • bash
  • elvish
  • fish
  • powershell
  • zsh
  • --print-manpage — generate man page. she's self-aware. 💅
  • --tls-cert <TLS_CERT> — the TLS certificate to use.
  • --tls-key <TLS_KEY> — the TLS private key to use.
  • --readme — enable README.md rendering in directories. finally, your readme gets its main character moment.
  • -I, --disable-indexing — disable indexing.

this will prevent directory listings from being generated and return an error instead. no peeking. 🔒

  • --enable-webdav — enable read-only WebDAV support (PROPFIND requests).
  • --size-display <SIZE_DISPLAY> [default: human] — show served file size in… well, that depends.

possible values:

  • human
  • exact

this allows serving files from a different URL than the browsing instance. super 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. so like, that's on you. 🙈

  • --log-color <LOG_COLOR> [default: auto] — set the color style of the log output.

"auto" (default) enables colors only when the output is a terminal. "always" always enables colors. "never" always disables colors.

possible values:

  • auto
  • always
  • never
  • -h, --help — print help (see a summary with '-h').
  • -V, --version — print version.
  • [PATH] — which path to serve. the whole point, honestly. 🎀

🌈 VERSION 🌈

v0.35.0 — that's the one, bestie.

👑 AUTHORS 👑

  • Sven-Hendrik Haase <svenstaro@gmail.com>
  • Boastful Squirrel <boastful.squirrel@gmail.com>

and that's the whole page, we ate and left no crumbs. 💖 this was miniserve version 0.35.0, documented as miniserve(1) — go forth and serve files, you gorgeous genius. no cap. 🫶✨

📦 where this page comes from