Document CLI usage

README.md

@@ -2,12 +2,12 @@
 
 ![](http://imgur.com/vhub5.png)
 
-A simple static file server middleware. Use it with a raw http server or
-express/connect!
+A simple static file server middleware. Use it with a raw http server,
+express/connect or on the CLI!
 
 # Examples:
 
-## express 3.0.x
+## express 4.x
 
 ``` js
 var http = require('http');
@@ -33,18 +33,46 @@ http.createServer(
 
 console.log('Listening on :8080');
 ```
+
 ### fall through
 To allow fall through to your custom routes:
 
 ```js
 ecstatic({ root: __dirname + '/public', handleError: false })
 ```
 
+## CLI
+
+```sh
+#!/bin/bash
+
+ecstatic ./public --show-dir --auto-index --port 8080
+```
+
+# Install:
+
+For using ecstatic as a library, just npm install it into your project:
+
+```sh
+npm install --save ecstatic
+```
+
+For using ecstatic as a cli tool, either npm install it globally:
+
+```sh
+npm install ecstatic -g
+```
+
+or install it locally and use npm runscripts to add it to your $PATH, or
+reference it directly with `./node_modules/.bin/ecstatic`.
+
+
 # API:
 
 ## ecstatic(opts);
+## $ ecstatic [dir?] {options} --port PORT
 
-Pass ecstatic an options hash, and it will return your middleware!
+In node, pass ecstatic an options hash, and it will return your middleware!
 
 ```js
 var opts = {
@@ -70,42 +98,57 @@ var opts = {
 If `opts` is a string, the string is assigned to the root folder and all other
 options are set to their defaults.
 
+When running in CLI mode, all options work as above, passed in
+[optimist](https://github.com/substack/node-optimist) style. `port` defaults to
+`8000`. If a `dir` or `--root dir` argument is not passed, ecsatic will
+serve the current dir. Ecstatic also respects the PORT environment variable.
+
 ### `opts.root`
+### `--root {root}`
 
 `opts.root` is the directory you want to serve up.
 
 ### `opts.port`
+### `--port {port}
 
-`opts.port` is the port you want ecstatic to listen to. Defaults to 8000.
+`opts.port` is the port you want ecstatic to listen to. Defaults to 8000. In
+CLI mode, this can be overridden with the `--port` flag or with the PORT
+environment variable.
 
 ### `opts.baseDir`
+### `--baseDir {dir}`
 
 `opts.baseDir` is `/` by default, but can be changed to allow your static files
 to be served off a specific route. For example, if `opts.baseDir === "blog"`
 and `opts.root = "./public"`, requests for `localhost:8080/blog/index.html` will
 resolve to `./public/index.html`.
 
 ### `opts.cache`
+### `--cache {value}`
 
 Customize cache control with `opts.cache` , if it is a number then it will set max-age in seconds.
 Other wise it will pass through directly to cache-control. Time defaults to 3600 s (ie, 1 hour).
 
 If it is a function, it will be executed on every request, and passed the pathname.  Whatever it returns, string or number, will be used as the cache control header like above.
 
 ### `opts.showDir`
+### `--no-showDir`
 
 Turn **off** directory listings with `opts.showDir === false`. Defaults to **true**.
 
 ### `opts.showDotfiles`
+### `--no-showDotfiles`
 
 Exclude dotfiles from directory listings with `opts.showDotfiles === false`. Defaults to **true**.
 
 ### `opts.humanReadable`
+### `--no-human-readable`
 
 If showDir is enabled, add human-readable file sizes. Defaults to **true**.
 Aliases are `humanreadable` and `human-readable`.
 
 ### `opts.headers`
+### `--H {HeaderA: valA} [--H {HeaderB: valB}]`
 
 Set headers on every response. `opts.headers` can be an object mapping string
 header names to string header values, a colon (:) separated string, or an array
@@ -119,17 +162,20 @@ $ ecstatic ./public -p 5000 -H 'Access-Control-Allow-Origin: *'
 ```
 
 ### `opts.si`
+### `--si`
 
 If showDir and humanReadable are enabled, print file sizes with base 1000 instead
 of base 1024. Name is inferred from cli options for `ls`. Aliased to `index`, the
 equivalent option in Apache.
 
 ### `opts.autoIndex`
+### `--no-autoindex`
 
 Serve `/path/index.html` when `/path/` is requested.
 Turn **off** autoIndexing with `opts.autoIndex === false`. Defaults to **true**.
 
 ### `opts.defaultExt`
+### `--defaultExt {ext}`
 
 Turn on default file extensions with `opts.defaultExt`. If `opts.defaultExt` is
 true, it will default to `html`. For example if you want a request to `/a-file`
@@ -138,22 +184,26 @@ to resolve to `./public/a-file.html`, set this to `true`. If you want
 `json`.
 
 ### `opts.gzip`
+### `--gzip`
 
 Set `opts.gzip === true` in order to turn on "gzip mode," wherein ecstatic will
 serve `./public/some-file.js.gz` in place of `./public/some-file.js` when the
 gzipped version exists and ecstatic determines that the behavior is appropriate.
 
 ### `opts.serverHeader`
+### `--no-server-header`
 
 Set `opts.serverHeader` to false in order to turn off setting the `Server` header
 on all responses served by ecstatic.
 
 ### `opts.contentType`
+### `--content-type {type}`
 
 Set `opts.contentType` in order to change default Content-Type header value.
 Defaults to **application/octet-stream**.
 
 ### `opts.mimeTypes`
+### `--mime-types {filename}`
 
 Add new or override one or more mime-types. This affects the HTTP Content-Type header.
 Can either be a path to a [`.types`](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types) file or an object hash of type(s).
@@ -165,19 +215,23 @@ Can either be a path to a [`.types`](http://svn.apache.org/repos/asf/httpd/httpd
 Turn **off** handleErrors to allow fall-through with `opts.handleError === false`, Defaults to **true**.
 
 ### `opts.weakEtags`
+### `--weak-etags`
 
 Set `opts.weakEtags` to true in order to generate weak etags instead of strong etags. Defaults to **false**. See `opts.weakCompare` as well.
 
 ### `opts.weakCompare`
+### `--weak-compare`
 
 Turn **on** weakCompare to allow the weak comparison function for etag validation. Defaults to **false**.
 See https://www.ietf.org/rfc/rfc2616.txt Section 13.3.3 for more details.
 
 ### `opts.handleOptionsMethod`
+### `--handle-options-method`
 
 Set handleOptionsMethod to true in order to respond to 'OPTIONS' calls with any standard/set headers. Defaults to **false**. Useful for hacking up CORS support.
 
 ### `opts.cors`
+### `--cors`
 
 This is a **convenience** setting which turns on `handleOptionsMethod` and sets the headers **Access-Control-Allow-Origin: \*** and **Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since**. This *should* be enough to quickly make cross-origin resource sharing work between development APIs. More advanced usage can come either from overriding these headers with the headers argument, or by using the `handleOptionsMethod` flag and then setting headers "manually." Alternately, just do it in your app using separate middlewares/abstractions.
 
@@ -191,14 +245,6 @@ This works more or less as you'd expect.
 
 This returns another middleware which will attempt to show a directory view. Turning on auto-indexing is roughly equivalent to adding this middleware after an ecstatic middleware with autoindexing disabled.
 
-### `ecstatic` command
-
-to start a standalone static http server,
-run `npm install -g ecstatic` and then run `ecstatic [dir?] [options] --port PORT`
-all options work as above, passed in [optimist](https://github.com/substack/node-optimist) style.
-`port` defaults to `8000`. If a `dir` or `--root dir` argument is not passed, ecsatic will
-serve the current dir. Ecstatic also respects the PORT environment variable.
-
 # Tests:
 
 Ecstatic has a fairly extensive test suite. You can run it with:

example/cli.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+../lib/ecstatic.js ./public --show-dir --auto-index --port 8080
+