# sirv-cli
> A lightweight CLI program to serve static sites~!
Latest version **3.0.1** (published 2025-02-17) · MIT license · 0 weekly downloads
## Install
```sh
npm install sirv-cli
pnpm add sirv-cli
yarn add sirv-cli
bun add sirv-cli
```
Provides the command `sirv`.
## Health
**Score 30/100 (F)** — status: maintenance-mode.
Positive: esm support; no vulnerabilities.
Warnings: low downloads; no types.
Negative: stale; low maintenance score.
## Facts
| | |
|---|---|
| Version | 3.0.1 |
| Published | 2025-02-17 |
| First published | 2018-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 8 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Luke Edwards |
| Maintainers | lukeed |
## Links
- npm: https://www.npmjs.com/package/sirv-cli
- Repository: https://github.com/lukeed/sirv
- Homepage: https://github.com/lukeed/sirv#readme
- Issues: https://github.com/lukeed/sirv/issues
- npm.io page: https://npm.io/package/sirv-cli
## Dependencies (8)
- [sade](https://npm.io/package/sade.md) ^1.6.0
- [sirv](https://npm.io/package/sirv.md) ^3.0.0
- [kleur](https://npm.io/package/kleur.md) ^4.1.4
- [semiver](https://npm.io/package/semiver.md) ^1.0.0
- [get-port](https://npm.io/package/get-port.md) ^5.1.1
- [tinydate](https://npm.io/package/tinydate.md) ^1.0.0
- [local-access](https://npm.io/package/local-access.md) ^1.0.1
- [console-clear](https://npm.io/package/console-clear.md) ^1.1.0
## Recent versions
- 3.0.1 (latest) — 2025-02-17
- 1.0.0-next.9 (next) — 2020-06-07
- 3.0.0 — 2024-10-11
- 2.0.2 — 2022-01-17
- 2.0.1 — 2021-12-29
- 2.0.0 — 2021-12-29
- 1.0.14 — 2021-08-14
- 1.0.13 — 2021-08-13
- 1.0.12 — 2021-05-24
- 1.0.11 — 2021-01-30
- 1.0.10 — 2020-12-07
- 1.0.9 — 2020-12-05
- 1.0.8 — 2020-10-19
- 1.0.7 — 2020-10-16
- 1.0.6 — 2020-08-12
- … 38 more at https://npm.io/package/sirv-cli/versions
## README
sirv-cli
A lightweight CLI program to serve static sites~!
Quickly start a server to preview the assets of _any_ directory!
## Install
```
$ npm install --save sirv-cli
```
> **Note:** This module can also be installed and used globally~!
## Usage
> **Important:** The `HOST` and `PORT` environment variables will override the `--host` and `--port` flags, respectively.
```
$ sirv --help
Description
Run a static file server
Usage
$ sirv [dir] [options]
Options
-D, --dev Enable "dev" mode
-e, --etag Enable "ETag" header
-d, --dotfiles Enable dotfile asset requests
-c, --cors Enable "CORS" headers to allow any origin requestor
-G, --gzip Send precompiled "*.gz" files when "gzip" is supported (default true)
-B, --brotli Send precompiled "*.br" files when "brotli" is supported (default true)
-m, --maxage Enable "Cache-Control" header & define its "max-age" value (sec)
-i, --immutable Enable the "immutable" directive for "Cache-Control" header
-k, --http2 Enable the HTTP/2 protocol. Requires Node.js 8.4.0+
-C, --cert Path to certificate file for HTTP/2 server
-K, --key Path to certificate key for HTTP/2 server
-P, --pass Passphrase to decrypt a certificate key
-s, --single Serve as single-page application with "index.html" fallback
-I, --ignores Any URL pattern(s) to ignore "index.html" assumptions
-q, --quiet Disable logging to terminal
-H, --host Hostname to bind (default localhost)
-p, --port Port to bind (default 8080)
-v, --version Displays current version
-h, --help Displays this message
Examples
$ sirv build --cors --port 8888
$ sirv public --quiet --etag --maxage 31536000 --immutable
$ sirv public --http2 --key priv.pem --cert cert.pem
$ sirv public -qeim 31536000
$ sirv --port 8888 --etag
$ sirv --host --dev
```
## Network Access
For security reasons, `sirv-cli` **does not** expose your server to the network by default.
This means that your machine, _and only your machine_, will be able to access the `localhost` server.
If, however, your coworker wants to access the server from their computer, or you want to preview your work on a mobile device, you must use the `--host` flag. Only _then_ will your server be accessible to other devices on the same network.
Using `--host` without a value is equivalent to `--host 0.0.0.0`, which is makes it discoverable publicly. You may customize this by passing a different value – but you probably don't need to!
> **Important:** Only the `Network:` address is accessible to others. The `Local:` address is still private to you.
## HTTP/2
> **Note:** Requires Node.js v8.4.0 or later.
The `--key` and `--cert` flags are required since no browsers support [unencrypted HTTP/2](https://http2.github.io/faq/#does-http2-require-encryption).
These must be valid file paths (resolved from `process.cwd()`), which are read and passed into [`http2.createSecureServer`](https://nodejs.org/api/http2.html#http2_http2_createsecureserver_options_onrequesthandler).
You can generate a certificate and key for local development quickly with:
```sh
$ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
-keyout localhost-key.pem -out localhost-cert.pem
# Now we can run a HTTP/2 server
$ sirv --http2 --key localhost-key.pem --cert localhost-cert.pem
```
To bypass the "third party verification" error page, you may use [`mkcert`](https://github.com/FiloSottile/mkcert) to generate a locally-trusted development certificate:
```sh
$ mkcert -install
$ mkcert -key-file localhost-key.pem -cert-file localhost-cert.pem localhost 127.0.0.1
# Now we can run a HTTP/2 server with verified SSL
$ sirv --http2 --key localhost-key.pem --cert localhost-cert.pem
```
## Single Page Applications
You must pass the `--single` flag to enable single-page application ("SPA") mode. This will, for example, serve your directory's `index.html` file when an unknown _path_ (eg; `/foo/bar`) does not resolve to another page.
> **Note:** Please refer to [`opts.single`](https://github.com/lukeed/sirv/tree/master/packages/sirv#optssingle) for the lookup sequence.
Any asset requests (URLs that end with an extension) ignore `--single` behavior and will send a `404` response instead of the "index.html" fallback. To ignore additional paths, pass URL patterns to the `--ignores` argument.
```sh
# Don't include "/blog*" or "/portfolio*" pages into SPA
$ sirv public --single --ignores "^/blog" --ignores "^/portfolio"
```
You may pass a string to customize which file should be sent as fallback.
In other words, `--single shell.html` will send the directory's `shell.html` file instead of its `index.html` file.
## Production
When using `sirv-cli` for production file-serving, you should:
1) Ensure `--dev` is not used
2) Enable HTTP/2 (`--http2`) with valid key and cert
3) Precompile brotli and/or gzip file variants
4) Enable `--gzip` and/or `--brotli` flags
For maximum performance, you should also use `--quiet` to disable the I/O from logging.
> **Notice:**
While `sirv-cli` is certainly "production ready", using a CDN in production is always recommended.
Especially when performance is a concern, there are much better solutions than using Node.js as a file server.
Most everything has HTTP/2 and "SPA" support nowadays – consider NGINX or [h2o](https://h2o.examp1e.net/).
## License
MIT © [Luke Edwards](https://lukeed.com)
---
_Source: https://npm.io/package/sirv-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
