#server #http

app serve-directory

Serve a directory with a single command!

1 unstable release

0.1.0 Oct 9, 2021

#2558 in Command line utilities

Download history 9/week @ 2023-08-04 14/week @ 2023-08-11 100/week @ 2023-08-18 4/week @ 2023-08-25 4/week @ 2023-09-01 5/week @ 2023-09-08 47/week @ 2023-09-15 26/week @ 2023-09-22 5/week @ 2023-09-29 9/week @ 2023-10-06 12/week @ 2023-10-13 113/week @ 2023-10-20 20/week @ 2023-10-27 12/week @ 2023-11-03 110/week @ 2023-11-10 10/week @ 2023-11-17

164 downloads per month

MIT license

122 lines

pipeline status


serve-directory is a simple command line utility to serve static files from the command line. In the general case, we really mean simple. To start a web server serving the contents of the current directory and its subdirectories, just run the executable without arguments.

$ serve-directory

Files are accessed based on their relative position to the target folder. Consider the following (abbreviated) rust project structure:

Project Structure:          Route:
 .                          /
 ├─ src/                    /src
 │  ├─ main.rs              /src/main.rs
 │  └─ stuff.rs             /src/stuff.rs
 ├─ target/                 /target
 │  └─ debug/               /target/debug
 │     └─ app.exe           /target/debug/app.exe
 └─ README.md               /README.md

As you can see, the correlation between the file structure and the route is quite natural.

Why Should I Care?

Sometimes, configuring network folders is way more work than it's worth to simply pass a couple files between machines, especially if you're moving files to or from a headless system. While you could use a tool like SFTP, serve-directory provides a nice graphical way to browse the filesystem in a web browser that should prove less daunting for new users. It also allows downloading files to multiple clients without having to log in through SSH multiple times.

It's also easy and doesn't require any additional setup (provided the user has a compiled executable). Most users already have a browser on their machine. And, in the event that the user does not, they can use curl or wget to download files over HTTP.

While it's evident that there's a use case for a simple and erogonomic HTTP file server, why would you use serve-directory instead of one of the more established options like the serve package for NodeJS? I will concede that in many cases, serve will probably suit your needs better. However, because serve-directory is written in Rust and natively compiled, it can be used and distributed in a single executable without a runtime.

Installation and Usage

The recommended way to install the latest version of this application from crates.io is using cargo:

$ cargo install serve-directory

Alternatively, you can build it from source with cargo, then add the application to your PATH.

$ cargo build --release
$ cp ./target/release/serve-directory ~/bin/serve-directory

Different features of the application are controlled through command line arguments. You can see a full list of arguments using the -h or --help flag.

$ serve-directory --help

In general, simply point the application at the desired directory. The program will attempt to determine your current IP address and bind to that interface. To change the port that the application binds to, use the -p flag. For example, this command will serve content in the ~/www directory on port 80.

Note that in practice, you may have to run the program as root in order to access lower-numbered ports. Simply add a sudo to the start of the command.

$ serve-directory -p 80 ~/www


A special thank you to the serve project for providing inspiration for this tool! Thank you as well to Material-UI for the icons used on the directory webpage!

This project is made possible by the work of the following great libraries:

Crate Owners
build_html Joseph Skubal
env_logger The Rust Project Developers
lazy_static The Rust Libs Team
local_ipaddress Egmkang Wang
log The Rust Project Developers
structopt Guillaume Pinot
tokio Tokio Contributors
warp Sean McArthur

And, of course, the Rust language!


This project is licensed under the MIT license. Feel free to use and remix it as you wish.

Copyright (C) 2020-21 Joseph Skubal


~334K SLoC