update usage for all commands

put @ inside <@scope>
simplify completion usage
add [@<version>] to edit
remove extraneous from install

doc/cli/npm-bin.md

@@ -3,7 +3,7 @@ npm-bin(1) -- Display npm bin folder
 
 ## SYNOPSIS
 
-    npm bin
+    npm bin [--global]
 
 ## DESCRIPTION
 

doc/cli/npm-bugs.md

@@ -3,8 +3,7 @@ npm-bugs(1) -- Bugs for a package in a web browser maybe
 
 ## SYNOPSIS
 
-    npm bugs <pkgname>
-    npm bugs (with no args in a package dir)
+    npm bugs [<pkgname>]
 
 ## DESCRIPTION
 

doc/cli/npm-build.md

@@ -3,7 +3,7 @@ npm-build(1) -- Build a package
 
 ## SYNOPSIS
 
-    npm build <package-folder>
+    npm build [<package-folder>]
 
 * `<package-folder>`:
   A folder containing a `package.json` file in its root.

doc/cli/npm-completion.md

@@ -3,7 +3,7 @@ npm-completion(1) -- Tab Completion for npm
 
 ## SYNOPSIS
 
-    . <(npm completion)
+    source <(npm completion)
 
 ## DESCRIPTION
 
@@ -12,7 +12,10 @@ Enables tab-completion in all npm commands.
 The synopsis above
 loads the completions into your current shell.  Adding it to
 your ~/.bashrc or ~/.zshrc will make the completions available
-everywhere.
+everywhere:
+
+    npm completion >> ~/.bashrc
+    npm completion >> ~/.zshrc
 
 You may of course also pipe the output of npm completion to a file
 such as `/usr/local/etc/bash_completion.d/npm` if you have a system

doc/cli/npm-config.md

@@ -8,7 +8,6 @@ npm-config(1) -- Manage the npm configuration files
     npm config delete <key>
     npm config list
     npm config edit
-    npm c [set|get|delete|list]
     npm get <key>
     npm set <key> <value> [--global]
 

doc/cli/npm-deprecate.md

@@ -3,7 +3,7 @@ npm-deprecate(1) -- Deprecate a version of a package
 
 ## SYNOPSIS
 
-    npm deprecate <name>[@<version>] <message>
+    npm deprecate <pkg>[@<version>] <message>
 
 ## DESCRIPTION
 

doc/cli/npm-docs.md

@@ -4,9 +4,9 @@ npm-docs(1) -- Docs for a package in a web browser maybe
 ## SYNOPSIS
 
     npm docs [<pkgname> [<pkgname> ...]]
-    npm docs (with no args in a package dir)
+    npm docs .
     npm home [<pkgname> [<pkgname> ...]]
-    npm home (with no args in a package dir)
+    npm home .
 
 ## DESCRIPTION
 

doc/cli/npm-edit.md

@@ -3,7 +3,7 @@ npm-edit(1) -- Edit an installed package
 
 ## SYNOPSIS
 
-    npm edit <name>[@<version>]
+    npm edit <pkg>[@<version>]
 
 ## DESCRIPTION
 

doc/cli/npm-explore.md

@@ -3,7 +3,7 @@ npm-explore(1) -- Browse an installed package
 
 ## SYNOPSIS
 
-    npm explore <name> [ -- <cmd>]
+    npm explore <pkg> [ -- <cmd>]
 
 ## DESCRIPTION
 

doc/cli/npm-help-search.md

@@ -3,7 +3,7 @@ npm-help-search(1) -- Search npm help documentation
 
 ## SYNOPSIS
 
-    npm help-search some search terms
+    npm help-search <text>
 
 ## DESCRIPTION
 

doc/cli/npm-help.md

@@ -3,8 +3,7 @@ npm-help(1) -- Get help on npm
 
 ## SYNOPSIS
 
-    npm help <topic>
-    npm help some search terms
+    npm help <term> [<terms..>]
 
 ## DESCRIPTION
 

doc/cli/npm-init.md

@@ -3,7 +3,7 @@ npm-init(1) -- Interactively create a package.json file
 
 ## SYNOPSIS
 
-    npm init [-f|--force|-y|--yes]
+    npm init [--force|-f|--yes|-y]
 
 ## DESCRIPTION
 

doc/cli/npm-install.md

@@ -3,15 +3,17 @@ npm-install(1) -- Install a package
 
 ## SYNOPSIS
 
-    npm install (with no args in a package dir)
+    npm install (with no args, in package dir)
+    npm install [<@scope>/]<name>
+    npm install [<@scope>/]<name>@<tag>
+    npm install [<@scope>/]<name>@<version>
+    npm install [<@scope>/]<name>@<version range>
     npm install <tarball file>
     npm install <tarball url>
     npm install <folder>
-    npm install [@<scope>/]<name> [--save|--save-dev|--save-optional] [--save-exact]
-    npm install [@<scope>/]<name>@<tag>
-    npm install [@<scope>/]<name>@<version>
-    npm install [@<scope>/]<name>@<version range>
-    npm i (with any of the previous argument usage)
+
+    alias: npm i
+    common options: [--save|--save-dev|--save-optional] [--save-exact]
 
 ## DESCRIPTION
 
@@ -71,7 +73,7 @@ after packing it up into a tarball (b).
 
           npm install https://github.com/indexzero/forever/tarball/v0.5.6
 
-* `npm install [@<scope>/]<name> [--save|--save-dev|--save-optional]`:
+* `npm install [<@scope>/]<name> [--save|--save-dev|--save-optional]`:
 
     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
     `npm-config(7)`.)
@@ -124,7 +126,7 @@ after packing it up into a tarball (b).
     working directory, then it will try to install that, and only try to
     fetch the package by name if it is not valid.
 
-* `npm install [@<scope>/]<name>@<tag>`:
+* `npm install [<@scope>/]<name>@<tag>`:
 
     Install the version of the package that is referenced by the specified tag.
     If the tag does not exist in the registry data for that package, then this
@@ -135,7 +137,7 @@ after packing it up into a tarball (b).
           npm install sax@latest
           npm install @myorg/mypackage@latest
 
-* `npm install [@<scope>/]<name>@<version>`:
+* `npm install [<@scope>/]<name>@<version>`:
 
     Install the specified version of the package.  This will fail if the
     version has not been published to the registry.
@@ -145,7 +147,7 @@ after packing it up into a tarball (b).
           npm install sax@0.1.1
           npm install @myorg/privatepackage@1.5.0
 
-* `npm install [@<scope>/]<name>@<version range>`:
+* `npm install [<@scope>/]<name>@<version range>`:
 
     Install a version of the package matching the specified version range.  This
     will follow the same rules for resolving dependencies described in `package.json(5)`.

doc/cli/npm-link.md

@@ -3,9 +3,10 @@ npm-link(1) -- Symlink a package folder
 
 ## SYNOPSIS
 
-    npm link (in package folder)
-    npm link [@<scope>/]<pkgname>
-    npm ln (with any of the previous argument usage)
+    npm link (in package dir)
+    npm link [<@scope>/]<pkg>[@<version>]
+
+    alias: npm ln
 
 ## DESCRIPTION
 

doc/cli/npm-logout.md

@@ -3,7 +3,7 @@ npm-logout(1) -- Log out of the registry
 
 ## SYNOPSIS
 
-    npm logout [--registry=url] [--scope=@orgname]
+    npm logout [--registry=<url>] [--scope=<@scope>]
 
 ## DESCRIPTION
 

doc/cli/npm-ls.md

@@ -3,10 +3,9 @@ npm-ls(1) -- List installed packages
 
 ## SYNOPSIS
 
-    npm list [[@<scope>/]<pkg> ...]
-    npm ls [[@<scope>/]<pkg> ...]
-    npm la [[@<scope>/]<pkg> ...]
-    npm ll [[@<scope>/]<pkg> ...]
+    npm ls [[<@scope>/]<pkg> ...]
+
+    aliases: list, la, ll
 
 ## DESCRIPTION
 

doc/cli/npm-outdated.md

@@ -3,7 +3,7 @@ npm-outdated(1) -- Check for outdated packages
 
 ## SYNOPSIS
 
-    npm outdated [<name> [<name> ...]]
+    npm outdated [[<@scope>/]<pkg> ...]
 
 ## DESCRIPTION
 

doc/cli/npm-owner.md

@@ -3,9 +3,9 @@ npm-owner(1) -- Manage package owners
 
 ## SYNOPSIS
 
-    npm owner ls <package name>
-    npm owner add <user> <package name>
-    npm owner rm <user> <package name>
+    npm owner add <user> [<@scope>/]<pkg>
+    npm owner rm <user> [<@scope>/]<pkg>
+    npm owner ls [<@scope>/]<pkg>
 
 ## DESCRIPTION
 

doc/cli/npm-pack.md

@@ -3,15 +3,15 @@ npm-pack(1) -- Create a tarball from a package
 
 ## SYNOPSIS
 
-    npm pack [<pkg> [<pkg> ...]]
+    npm pack [[<@scope>/]<pkg>...]
 
 ## DESCRIPTION
 
 For anything that's installable (that is, a package folder, tarball,
-tarball url, name@tag, name@version, or name), this command will fetch
-it to the cache, and then copy the tarball to the current working
-directory as `<name>-<version>.tgz`, and then write the filenames out to
-stdout.
+tarball url, name@tag, name@version, name, or scoped name), this
+command will fetch it to the cache, and then copy the tarball to the
+current working directory as `<name>-<version>.tgz`, and then write
+the filenames out to stdout.
 
 If the same package is specified multiple times, then the file will be
 overwritten the second time.

doc/cli/npm-prune.md

@@ -3,8 +3,7 @@ npm-prune(1) -- Remove extraneous packages
 
 ## SYNOPSIS
 
-    npm prune [<name> [<name ...]]
-    npm prune [<name> [<name ...]] [--production]
+    npm prune [[<@scope>/]<pkg>...] [--production]
 
 ## DESCRIPTION
 

doc/cli/npm-publish.md

@@ -4,8 +4,10 @@ npm-publish(1) -- Publish a package
 
 ## SYNOPSIS
 
-    npm publish <tarball> [--tag <tag>] [--access <public|restricted>]
-    npm publish <folder> [--tag <tag>] [--access <public|restricted>]
+    npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>]
+
+    Publishes '.' if no argument supplied
+    Sets tag 'latest' if no --tag specified
 
 ## DESCRIPTION
 

doc/cli/npm-rebuild.md

@@ -3,11 +3,9 @@ npm-rebuild(1) -- Rebuild a package
 
 ## SYNOPSIS
 
-    npm rebuild [<name> [<name> ...]]
-    npm rb [<name> [<name> ...]]
+    npm rebuild [[<@scope>/<name>]...]
 
-* `<name>`:
-  The package to rebuild
+    alias: npm rb
 
 ## DESCRIPTION
 

doc/cli/npm-repo.md

@@ -3,8 +3,7 @@ npm-repo(1) -- Open package repository page in the browser
 
 ## SYNOPSIS
 
-    npm repo <pkgname>
-    npm repo (with no args in a package dir)
+    npm repo [<pkg>]
 
 ## DESCRIPTION
 

doc/cli/npm-root.md

@@ -3,7 +3,7 @@ npm-root(1) -- Display npm root
 
 ## SYNOPSIS
 
-    npm root
+    npm root [-g]
 
 ## DESCRIPTION
 

doc/cli/npm-run-script.md

@@ -3,8 +3,9 @@ npm-run-script(1) -- Run arbitrary package scripts
 
 ## SYNOPSIS
 
-    npm run-script [command] [-- <args>]
-    npm run [command] [-- <args>]
+    npm run-script <command> [-- <args>...]
+
+    alias: npm run
 
 ## DESCRIPTION
 

doc/cli/npm-search.md

@@ -4,8 +4,8 @@ npm-search(1) -- Search for packages
 ## SYNOPSIS
 
     npm search [--long] [search terms ...]
-    npm s [search terms ...]
-    npm se [search terms ...]
+
+    aliases: s, se
 
 ## DESCRIPTION
 

doc/cli/npm-star.md

@@ -3,8 +3,8 @@ npm-star(1) -- Mark your favorite packages
 
 ## SYNOPSIS
 
-    npm star <pkgname> [<pkg>, ...]
-    npm unstar <pkgname> [<pkg>, ...]
+    npm star [<pkg>...]
+    npm unstar [<pkg>...]
 
 ## DESCRIPTION
 

doc/cli/npm-stars.md

@@ -3,8 +3,7 @@ npm-stars(1) -- View packages marked as favorites
 
 ## SYNOPSIS
 
-    npm stars
-    npm stars [username]
+    npm stars [<user>]
 
 ## DESCRIPTION
 

doc/cli/npm-tag.md

@@ -3,7 +3,8 @@ npm-tag(1) -- Tag a published version
 
 ## SYNOPSIS
 
-    npm tag <name>@<version> [<tag>]
+    [DEPRECATED] npm tag <name>@<version> [<tag>]
+    See `dist-tag`
 
 ## DESCRIPTION
 

doc/cli/npm-uninstall.md

@@ -3,8 +3,9 @@ npm-rm(1) -- Remove a package
 
 ## SYNOPSIS
 
-    npm uninstall [@<scope>/]<package> [--save|--save-dev|--save-optional]
-    npm rm (with any of the previous argument usage)
+    npm uninstall [<@scope>/]<pkg>[@<version>]... [--save|--save-dev|--save-optional]
+
+    aliases: remove, rm, r, un, unlink
 
 ## DESCRIPTION
 

doc/cli/npm-unpublish.md

@@ -3,7 +3,7 @@ npm-unpublish(1) -- Remove a package from the registry
 
 ## SYNOPSIS
 
-    npm unpublish [@<scope>/]<name>[@<version>]
+    npm unpublish [<@scope>/]<pkg>[@<version>]
 
 ## WARNING