update how to run

Author: cooper

README.md

@@ -29,6 +29,10 @@ see the [configuration spec](doc/configuration.md) for all options.
 
 ## run
 
+the easiest way to get started is run the setup wizard:
+
 ```sh
-quiki quiki.conf    # or $GOPATH/bin/quiki
-```
+quiki -w        # or $GOPATH/bin/quiki
+```
+
+for all options see [RUNNING](RUNNING.md).

RUNNING.md

@@ -0,0 +1,106 @@
+# Running
+
+The `quiki` executable can be used for several different functions.
+
+Please note: it is intended to be run as a non-super user.
+
+# Wizard
+
+To set up quiki webserver for the first time, run the setup wizard with
+```
+quiki -w
+```
+
+### Alternate host or port
+The server by default binds to all available hosts on port 8080. If you need to do
+something different, you can specify them to the wizard like:
+```
+quiki -w -bind=1.2.3.4 -port=9091
+```
+
+### Alternate config location
+By default, the wizard creates a directory at `~/quiki` to store your quiki
+configuration and sites. It will write the configuration file to `~/quiki/quiki.conf`.
+If you want to store the config elsewhere, you can specify like so:
+```
+quki -w -config=/path/to/quiki.conf
+```
+
+### Admin account setup
+When running with `-w`, after the configuration file is written, the server
+begins listening. You should navigate your browser to the adminifier setup page,
+e.g. `http://localhost:8080/admin/create-user`. Here, complete the form to set
+up your first admin user.
+
+The form requests an authentication token, which is printed to stdout to copy
+and paste. You can also find it designated as `@adminifier.token` in the webserver
+config, usually at `~/quiki/quiki.conf`.
+
+It also allows you to specify a location to store your wiki sites. This will be
+prepopulated with the recommended location which is the `wikis` dir relative
+to the config location, typically `~/quiki/wikis`.
+
+Upon successful completion of this form, you are logged in and ready to create
+your first wiki!
+
+# Webserver
+
+To run the quiki webserver if you've already set it up, simply run
+```
+quiki
+```
+This will assume the webserver config path of `~/quiki/quiki.conf`.
+
+### Alternate config location
+To run with a different config, use
+```
+quiki -config=/path/to/quiki.conf
+```
+
+### Override host or port
+The host and port typically are specified in the webserver config file.
+If desired, you can explicitly override them via the command line args:
+```
+quiki -bind=1.2.3.4 -port=9091
+```
+
+# Standalone page
+
+Standalone page mode allows you to render a single quiki page file with
+no wiki context.
+
+```
+quiki path/to/my.page
+```
+
+### Standalone wiki
+
+Standalone wiki mode allows you to perform wiki operations without
+running the webserver.
+
+### Render page within a wiki
+
+To render a page within a wiki, use
+```
+quiki -wiki=/path/to/wiki some_page_name
+```
+This will, for example, render the page at
+`/path/to/wiki/pages/some_page_name.page` in the context of the specified
+wiki. The HTML is written to STDOUT, and then the program exits.
+
+### Pregeneration
+
+To pregenerate all the pages in a wiki, run without a page argument:
+```
+quiki -wiki=/path/to/wiki
+```
+
+# Interactive Mode
+
+Interactive mode reads quiki source from STDIN until reaching EOF (i.e. Ctrl-D).
+Then, it prints the HTML output to STDOUT and exits. 
+
+To run quiki in interactive mode, use
+```
+quiki -i
+```