Clarify args parsing, update docs

- Update yargs config
- Add examples etc. to --help message
- Update README.md

Author: RyanZim

README.md

@@ -1,7 +1,7 @@
-[![npm][npm]][npm-url]
-[![node][node]][node-url]
-[![deps][deps]][deps-url]
 [![tests][tests]][tests-url]
+[![cover][cover]][cover-url]
+[![deps][deps]][deps-url]
+[![npm][npm]][npm-url]
 [![code style][style]][style-url]
 [![chat][chat]][chat-url]
 
@@ -13,68 +13,72 @@
   <h1>PostCSS CLI</h1>
 </div>
 
-## Install
+## Installation
 
 ```bash
 npm i -D postcss-cli
 ```
 
 ## Usage
 
-```bash
-postcss [options] [input] [-o output|-d output-dir|-r] [--watch]
+```
+postcss [input.css] [OPTIONS] [--output|-o output.css] [--watch]
+
+Options:
+  -o, --output       Output file                                        [string]
+  -d, --dir          Output directory                                   [string]
+  -r, --replace      Replace (overwrite) the input file                [boolean]
+  -u, --use          List of postcss plugins to use                      [array]
+  -p, --parser       Custom postcss parser                              [string]
+  -t, --stringifier  Custom postcss stringifier                         [string]
+  -s, --syntax       Custom postcss syntax                              [string]
+  -w, --watch        Watch files for changes and recompile as needed   [boolean]
+  -x, --extension    Override the output file extension                 [string]
+  -e, --env          A shortcut for setting NODE_ENV                    [string]
+  -c, --config       Set a custom path to look for a config file        [string]
+  -m, --map          Create an external sourcemap
+  --no-map           Disable the default inline sourcemaps
+  -h, --help         Show help                                         [boolean]
+  -v, --version      Show version number                               [boolean]
+
+Examples:
+  postcss input.css -o output.css       Basic usage
+  cat input.css | postcss -u            Piping input & output
+  autoprefixer > output.css
+
+If no input files are passed, it reads from stdin. If neither -o, --dir, or
+--replace is passed, it writes to stdout.
+
+If there are multiple input files, the --dir or --replace option must be passed.
 ```
 
-## Options
-
-|Name|Default|Description|
-|:--:|:-----:|:----------|
-|**`--dir/-d`**|`undefined`|Directory destination|
-|**`--ext/-ex`**|`undefined`|Change Output File Extension|
-|**`--output/-o`**|`process.stdout`|File destination|
-|**`--replace/-r`**|`undefined`|Replace file(s) with output|
-|**`--parser/-p`**|`undefined`|[Custom Parser][parser] (e.g SugarSS)|
-|**`--syntax/-s`**|`undefined`|[Custom Syntax][syntax] (e.g Midas)|
-|**`--stringifier/-t`**|`undefined`|[Custom Stringifier][stringifier] (e.g ..)|
-|**`--map/-m`**|`{ inline: false }`|Enable external Sourcemaps|
-|**`--no-map`**|`false`|Disable Sourcemaps|
-|**`--watch/-w`**|`false`|Watch files && `postcss.config.js`for changes|
-|**`--help/-h`**|`undefined`|CLI Usage|
-|**`--version/-v`**|`undefined`|CLI Version|
-
-[parser]: https://github.com/postcss/postcss#custom-syntaxes
-
-#### `--map|-m`
+For more details on custom parsers, stringifiers and syntaxes, see the [postcss docs](https://github.com/postcss/postcss#syntaxes).
 
-Activate sourcemaps generation. By default inline sourcemaps are generated.
-You can use [advances source map options][sourcemaps].
+## Configuration
 
-#### [`--config|-c`](https://github.com/michael-ciniawsky/postcss-load-config)
+If you need to pass options to your plugins, or have a long plugin chain, you'll want to use a configuration file.
 
-```bash
-postcss -c|--config path/to/postcss.config.js
-```
-**postcss.config.js**
+Example `postcss.config.js`:
 
 ```js
-module.exports = (ctx) => ({
-  parser: ctx.options.parser ? 'sugarss' : false,
-  map: ctx.env === 'development' ? 'inline' : false,
-  plugins: {
-    'postcss-import': { root: ctx.file.dirname },
-    'postcss-nested': {},
-    'cssnano': ctx.env !== 'development' ? {} : false
-  }
-})
+module.exports = () => {
+  parser: 'sugarss',
+  plugins: [
+    require('postcss-import')({ /* Options */ }),
+    require('postcss-url')({
+      url: 'copy',
+      useHash: true
+    })
+  ]
+}
 ```
 
+Configuration files are handled by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config). Refer to the docs there for more details.
+
 
 [npm]: https://img.shields.io/npm/v/postcss-cli.svg
 [npm-url]: https://npmjs.com/package/postcss-cli
 
-[node]: https://img.shields.io/node/v/<name>-loader.svg
-[node-url]: https://nodejs.org
-
 [deps]: https://img.shields.io/gemnasium/postcss/postcss-cli.svg
 [deps-url]: https://gemnasium.com/postcss/postcss-cli
 

index.js

@@ -42,26 +42,81 @@ const version = () => {
 }
 
 const argv = require('yargs')
-  .usage(`${chalk.bold.red(logo)}\nUsage: \n\n$0 [--config|-c path/to/postcss.config.js] [input.css] [--output|-o output.css] [-watch|-w]`)
-  .alias('e', 'env').describe('e', 'Environment')
-  .alias('x', 'ext').describe('x', 'Extension')
-  .alias('c', 'config').describe('c', 'Config')
-  .alias('o', 'output').describe('o', 'Output')
-    .describe('concat', 'Concat Input')
-  .alias('d', 'dir').describe('d', 'Output Directory')
-  .alias('r', 'replace').describe('r', 'Replace File')
+  .usage(
+`${chalk.bold.red(logo)}
+Usage:
+
+  $0 [input.css] [OPTIONS] [--output|-o output.css] [--watch]`
+)
+  .option('o', {
+    alias: 'output',
+    desc: 'Output file',
+    type: 'string'
+  })
+  .option('d', {
+    alias: 'dir',
+    desc: 'Output directory',
+    type: 'string'
+  })
+  .option('r', {
+    alias: 'replace',
+    desc: 'Replace (overwrite) the input file',
+    type: 'boolean'
+  })
+  .option('u', {
+    alias: 'use',
+    desc: 'List of postcss plugins to use',
+    type: 'array'
+  })
+  .option('p', {
+    alias: 'parser',
+    desc: 'Custom postcss parser',
+    type: 'string'
+  })
+  .option('t', {
+    alias: 'stringifier',
+    desc: 'Custom postcss stringifier',
+    type: 'string'
+  })
+  .option('s', {
+    alias: 'syntax',
+    desc: 'Custom postcss syntax',
+    type: 'string'
+  })
+  .option('w', {
+    alias: 'watch',
+    desc: 'Watch files for changes and recompile as needed',
+    type: 'boolean'
+  })
+  .option('x', {
+    alias: 'ext',
+    desc: 'Override the output file extension',
+    type: 'string'
+  })
+  .option('e', {
+    alias: 'env',
+    desc: 'A shortcut for setting NODE_ENV',
+    type: 'string'
+  })
+  .option('c', {
+    alias: 'config',
+    desc: 'Set a custom path to look for a config file',
+    type: 'string'
+  })
   .alias('m', 'map')
-    .describe('m', 'External Sourcemap')
-    .describe('no-map', 'Disable Sourcemaps')
-  .alias('b', 'concat').describe('b', 'Concat Input')
-  .alias('u', 'use').describe('u', 'Plugin(s)').array('u')
-  .alias('p', 'parser').describe('p', 'Parser')
-  .alias('s', 'syntax').describe('s', 'Syntax')
-  .alias('t', 'stringifier').describe('t', 'Stringifier')
-  .alias('w', 'watch').describe('w', 'Watch')
-  .help('h').alias('h', 'help')
+    .describe('m', 'Create an external sourcemap')
+    .describe('no-map', 'Disable the default inline sourcemaps')
   .version(version).alias('v', 'version')
-  .requiresArg(['i', 'o'])
+  .help('h').alias('h', 'help')
+  .example('$0 input.css -o output.css', 'Basic usage')
+  .example('cat input.css | $0 -u autoprefixer > output.css', 'Piping input & output')
+  .epilog(
+`If no input files are passed, it reads from stdin. If neither -o, --dir, or --replace is passed, it writes to stdout.
+
+If there are multiple input files, the --dir or --replace option must be passed.
+
+For more details, please see https://github.com/postcss/postcss-cli`
+  )
   .argv
 
 let dir = argv.dir