update usage for all commands

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

35 files changed, 77 insertions, 70 deletions

diff --git a/doc/cli/npm-bin.md b/doc/cli/npm-bin.md
index 33863b457..8e1abbee8 100644
--- a/doc/cli/npm-bin.md
+++ b/doc/cli/npm-bin.md
@@ -3,7 +3,7 @@ npm-bin(1) -- Display npm bin folder
 
 ## SYNOPSIS
 
-    npm bin
+    npm bin [--global]
 
 ## DESCRIPTION
 
diff --git a/doc/cli/npm-bugs.md b/doc/cli/npm-bugs.md
index 002d9f755..d2ad534fa 100644
--- a/doc/cli/npm-bugs.md
+++ b/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
 
diff --git a/doc/cli/npm-build.md b/doc/cli/npm-build.md
index 4d3467a16..019f22585 100644
--- a/doc/cli/npm-build.md
+++ b/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.
diff --git a/doc/cli/npm-completion.md b/doc/cli/npm-completion.md
index bec0f6086..6c7f39356 100644
--- a/doc/cli/npm-completion.md
+++ b/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
diff --git a/doc/cli/npm-config.md b/doc/cli/npm-config.md
index 1d978c9de..119840ef0 100644
--- a/doc/cli/npm-config.md
+++ b/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]
 
diff --git a/doc/cli/npm-deprecate.md b/doc/cli/npm-deprecate.md
index e62579349..1be6f491b 100644
--- a/doc/cli/npm-deprecate.md
+++ b/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
 
diff --git a/doc/cli/npm-docs.md b/doc/cli/npm-docs.md
index 5db3d9f7e..f5064c55e 100644
--- a/doc/cli/npm-docs.md
+++ b/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
 
diff --git a/doc/cli/npm-edit.md b/doc/cli/npm-edit.md
index 6a73317b8..89ecfa877 100644
--- a/doc/cli/npm-edit.md
+++ b/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
 
diff --git a/doc/cli/npm-explore.md b/doc/cli/npm-explore.md
index fded53408..b66e08bfb 100644
--- a/doc/cli/npm-explore.md
+++ b/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
 
diff --git a/doc/cli/npm-help-search.md b/doc/cli/npm-help-search.md
index 7bf7401ba..0a40f1c43 100644
--- a/doc/cli/npm-help-search.md
+++ b/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
 
diff --git a/doc/cli/npm-help.md b/doc/cli/npm-help.md
index 7991b1d38..9fb96c9c2 100644
--- a/doc/cli/npm-help.md
+++ b/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
 
diff --git a/doc/cli/npm-init.md b/doc/cli/npm-init.md
index ec4c25bed..e90f9ef04 100644
--- a/doc/cli/npm-init.md
+++ b/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
 
diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md
index 2ccde25e0..b382b114f 100644
--- a/doc/cli/npm-install.md
+++ b/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)`.
diff --git a/doc/cli/npm-link.md b/doc/cli/npm-link.md
index b6d0c143a..344fcbf1a 100644
--- a/doc/cli/npm-link.md
+++ b/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
 
diff --git a/doc/cli/npm-logout.md b/doc/cli/npm-logout.md
index 867953c02..411ea67e6 100644
--- a/doc/cli/npm-logout.md
+++ b/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
 
diff --git a/doc/cli/npm-ls.md b/doc/cli/npm-ls.md
index fa93e836e..efd981d67 100644
--- a/doc/cli/npm-ls.md
+++ b/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
 
diff --git a/doc/cli/npm-outdated.md b/doc/cli/npm-outdated.md
index aa2a7d5dd..bdc9b9b8e 100644
--- a/doc/cli/npm-outdated.md
+++ b/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
 
diff --git a/doc/cli/npm-owner.md b/doc/cli/npm-owner.md
index b400f7637..1047a09bb 100644
--- a/doc/cli/npm-owner.md
+++ b/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
 
diff --git a/doc/cli/npm-pack.md b/doc/cli/npm-pack.md
index 42bc1564b..f44f5e362 100644
--- a/doc/cli/npm-pack.md
+++ b/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.
diff --git a/doc/cli/npm-prune.md b/doc/cli/npm-prune.md
index 846a04240..908912211 100644
--- a/doc/cli/npm-prune.md
+++ b/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
 
diff --git a/doc/cli/npm-publish.md b/doc/cli/npm-publish.md
index 8c447d0df..8e4da32cd 100644
--- a/doc/cli/npm-publish.md
+++ b/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
 
diff --git a/doc/cli/npm-rebuild.md b/doc/cli/npm-rebuild.md
index 728720868..437737d9f 100644
--- a/doc/cli/npm-rebuild.md
+++ b/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
 
diff --git a/doc/cli/npm-repo.md b/doc/cli/npm-repo.md
index 6bc6f3b37..523e135e8 100644
--- a/doc/cli/npm-repo.md
+++ b/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
 
diff --git a/doc/cli/npm-root.md b/doc/cli/npm-root.md
index ca99e1206..a1d5bf862 100644
--- a/doc/cli/npm-root.md
+++ b/doc/cli/npm-root.md
@@ -3,7 +3,7 @@ npm-root(1) -- Display npm root
 
 ## SYNOPSIS
 
-    npm root
+    npm root [-g]
 
 ## DESCRIPTION
 
diff --git a/doc/cli/npm-run-script.md b/doc/cli/npm-run-script.md
index 487bd5942..bed05bd37 100644
--- a/doc/cli/npm-run-script.md
+++ b/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
 
diff --git a/doc/cli/npm-search.md b/doc/cli/npm-search.md
index 4757ad320..e7e0defa0 100644
--- a/doc/cli/npm-search.md
+++ b/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
 
diff --git a/doc/cli/npm-star.md b/doc/cli/npm-star.md
index 5c076b3c3..87d90b560 100644
--- a/doc/cli/npm-star.md
+++ b/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
 
diff --git a/doc/cli/npm-stars.md b/doc/cli/npm-stars.md
index 7c28f5b2a..1e225be29 100644
--- a/doc/cli/npm-stars.md
+++ b/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
 
diff --git a/doc/cli/npm-tag.md b/doc/cli/npm-tag.md
index d7118d4e5..357c0862f 100644
--- a/doc/cli/npm-tag.md
+++ b/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
 
diff --git a/doc/cli/npm-uninstall.md b/doc/cli/npm-uninstall.md
index 72e3b7d45..73e39a5fb 100644
--- a/doc/cli/npm-uninstall.md
+++ b/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
 
diff --git a/doc/cli/npm-unpublish.md b/doc/cli/npm-unpublish.md
index 1d5fe9287..0a5731ee1 100644
--- a/doc/cli/npm-unpublish.md
+++ b/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
 
diff --git a/doc/cli/npm-update.md b/doc/cli/npm-update.md
index ce31c2891..30a0702d7 100644
--- a/doc/cli/npm-update.md
+++ b/doc/cli/npm-update.md
@@ -3,7 +3,7 @@ npm-update(1) -- Update a package
 
 ## SYNOPSIS
 
-    npm update [-g] [<name> [<name> ...]]
+    npm update [-g] [<pkg>...]
 
 ## DESCRIPTION
 
diff --git a/doc/cli/npm-version.md b/doc/cli/npm-version.md
index abcd25b3a..21295027f 100644
--- a/doc/cli/npm-version.md
+++ b/doc/cli/npm-version.md
@@ -5,6 +5,10 @@ npm-version(1) -- Bump a package version
 
     npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
 
+    'npm -v' or 'npm --version' to print npm version
+    'npm view <pkg> version' to view a package's published version
+    'npm ls' to inspect current package/dependency versions
+
 ## DESCRIPTION
 
 Run this in a package directory to bump the version and write the new
diff --git a/doc/cli/npm-view.md b/doc/cli/npm-view.md
index 683ed09f4..2330c016e 100644
--- a/doc/cli/npm-view.md
+++ b/doc/cli/npm-view.md
@@ -3,8 +3,9 @@ npm-view(1) -- View registry info
 
 ## SYNOPSIS
 
-    npm view [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...]
-    npm v [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...]
+    npm view [<@scope>/]<name>[@<version>] [<field>[.<subfield>]...]
+
+    aliases: info, show, v
 
 ## DESCRIPTION
 
diff --git a/doc/cli/npm-whoami.md b/doc/cli/npm-whoami.md
index 3ff8837ff..70b6a48f4 100644
--- a/doc/cli/npm-whoami.md
+++ b/doc/cli/npm-whoami.md
@@ -3,7 +3,7 @@ npm-whoami(1) -- Display npm username
 
 ## SYNOPSIS
 
-    npm whoami
+    npm whoami [--registry <registry>]
 
 ## DESCRIPTION