Docs: CLI

docs/cli/README.md

@@ -1 +1,99 @@
 # Neutrino CLI
+
+Using the command-line interface is the preferred way of interacting with Neutrino. Let's take a look at its usage.
+
+## `--help`
+
+Using `neutrino --help` will bring up the following help guide:
+
+```bash
+❯ neutrino --help
+Commands:
+  start           Build a project in development mode
+  build           Compile the source directory to a bundled build
+  test [files..]  Run all suites from the test directory or provided files
+
+Options:
+  --presets  A list of Neutrino presets used to configure the build    [array] [default: []]
+  --version  Show version number                                       [boolean]
+  --help     Show help                                                 [boolean]
+```
+
+## `--version`
+
+Using `--version` will output the current version of the Neutrino CLI to the console and exit.
+
+```bash
+❯ neutrino --version
+4.0.0
+```
+
+## `--presets`
+
+The `--presets` flag can be used in conjunction with any of the top-level commands to specify a collection of
+presets to load. These can be an npm package or a relative path to a module to load as a preset.
+
+```bash
+❯ neutrino start --presets neutrino-preset-react neutrino-preset-karma
+```
+
+The Neutrino CLI will still attempt to load any presets defined in the project's package.json located at
+`config.presets`. Presets passed via the CLI `--presets` will take precedence over presets defined in
+`config.presets`, meaning that options set by package.json presets can have their values overridden by
+`--presets` presets.
+
+## neutrino start
+
+Using the command `neutrino start` builds a project in development mode, also starting a development server or source
+watcher depending on the preset or config options used. This command sets the `NODE_ENV` environment variable to
+`development`.
+
+## neutrino build
+
+Using the command `neutrino build` builds a project in production mode, rendering static assets to the configured build
+output destination. This command sets the `NODE_ENV` environment variable to `production`.
+
+## neutrino test
+
+Using the command `neutrino test` passes execution onto a test runner preset. It is up to the preset being used to
+determine how source files are built or provided to tests. See your particular test preset for details. This
+command sets the `NODE_ENV` environment variable to `test`.
+
+Looking at the `--help` for `neutrino test`:
+
+```bash
+❯ neutrino test --help
+neutrino test [files..]
+
+Options:
+  --presets  A list of Neutrino presets used to configure the build    [array] [default: []]
+  --version  Show version number                                       [boolean]
+  --help     Show help                                                 [boolean]
+  --watch    Watch source files for changes and re-run tests           [boolean] [default: false]
+```
+
+Using the command `neutrino test` will execute every test file located in your
+[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish
+to run individually. It is important to note that when combined with the `--presets` parameter, you should use two
+dashes after the last preset to denote the end of the presets and the beginning of the test files.
+
+```bash
+❯ neutrino test a_test.js b_test.js
+```
+
+```bash
+❯ neutrino test --presets neutrino-preset-react neutrino-preset-karma -- a_test.js b_test.js
+```
+
+You can also pass a flag `--watch` to watch source files for changes and re-run tests, if your preset supports it.
+
+```bash
+❯ neutrino test --watch
+```
+
+## Exit codes
+
+When the CLI creates an instance of Neutrino, it waits for all commands to either resolve or reject their Promise.
+If the command succeeded, the CLI will exit with code `0`. If there was an error, the CLI will log the error
+to the console and exit with code `1`. This makes it easier to use Neutrino commands for status reasons, such
+as failing a pull request on continuous integration if any tests fail or if there are linter errors.

docs/usage.md

@@ -98,7 +98,7 @@ to run individually. It is important to note that when combined with the `--pres
 dashes after the last preset to denote the end of the presets and the beginning of the test files.
 
 ```bash
-neutrino build --presets PRESET_A PRESET_B -- a_test.js b_test.js
+neutrino test --presets PRESET_A PRESET_B -- a_test.js b_test.js
 ```
 
 ## Using multiple presets