update usage for all commands

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

34 files changed, 53 insertions, 51 deletions

diff --git a/lib/adduser.js b/lib/adduser.js
index 3b876f04b..79babe02c 100644
--- a/lib/adduser.js
+++ b/lib/adduser.js
@@ -11,7 +11,7 @@ try {
   crypto = process.binding("crypto") && require("crypto")
 } catch (ex) {}
 
-adduser.usage = "npm adduser\nThen enter stuff at the prompts"
+adduser.usage = "npm adduser [--registry=url] [--scope=@orgname] [--always-auth]"
 
 function adduser (args, cb) {
   if (!crypto) return cb(new Error(
diff --git a/lib/bin.js b/lib/bin.js
index 5465112d8..62922447b 100644
--- a/lib/bin.js
+++ b/lib/bin.js
@@ -3,7 +3,7 @@ module.exports = bin
 var npm = require("./npm.js")
 var osenv = require("osenv")
 
-bin.usage = "npm bin\nnpm bin -g\n(just prints the bin folder)"
+bin.usage = "npm bin [--global]"
 
 function bin (args, silent, cb) {
   if (typeof cb !== "function") cb = silent, silent = false
diff --git a/lib/bugs.js b/lib/bugs.js
index c63b76b41..c7f094bf3 100644
--- a/lib/bugs.js
+++ b/lib/bugs.js
@@ -1,6 +1,6 @@
 module.exports = bugs
 
-bugs.usage = "npm bugs <pkgname>"
+bugs.usage = "npm bugs [<pkgname>]"
 
 var npm = require("./npm.js")
   , log = require("npmlog")
diff --git a/lib/build.js b/lib/build.js
index 1c683da35..4c284311d 100644
--- a/lib/build.js
+++ b/lib/build.js
@@ -23,7 +23,7 @@ var npm = require("./npm.js")
   , writeFile = require("write-file-atomic")
 
 module.exports = build
-build.usage = "npm build <folder>\n(this is plumbing)"
+build.usage = "npm build [<folder>]"
 
 build._didBuild = {}
 build._noLC = {}
diff --git a/lib/completion.js b/lib/completion.js
index 1d26ffcf8..7ae7e4742 100644
--- a/lib/completion.js
+++ b/lib/completion.js
@@ -1,9 +1,7 @@
 
 module.exports = completion
 
-completion.usage = "npm completion >> ~/.bashrc\n"
-                 + "npm completion >> ~/.zshrc\n"
-                 + "source <(npm completion)"
+completion.usage = "source <(npm completion)"
 
 var npm = require("./npm.js")
   , npmconf = require("./config/core.js")
diff --git a/lib/dedupe.js b/lib/dedupe.js
index a51df149a..fc97ebf36 100644
--- a/lib/dedupe.js
+++ b/lib/dedupe.js
@@ -16,7 +16,7 @@ var log = require('npmlog')
 module.exports = dedupe
 module.exports.Deduper = Deduper
 
-dedupe.usage = 'npm dedupe'
+dedupe.usage = 'npm dedupe [package names...]'
 
 function dedupe (args, cb) {
   validate('AF', arguments)
diff --git a/lib/docs.js b/lib/docs.js
index 600d393a0..e28fb3e7f 100644
--- a/lib/docs.js
+++ b/lib/docs.js
@@ -1,8 +1,8 @@
 module.exports = docs
 
 docs.usage  = "npm docs <pkgname>"
-docs.usage += "\n"
-docs.usage += "npm docs ."
+            + "\nnpm docs ."
+
 
 var npm = require("./npm.js")
   , opener = require("opener")
diff --git a/lib/edit.js b/lib/edit.js
index ddf501d54..a504b10d1 100644
--- a/lib/edit.js
+++ b/lib/edit.js
@@ -1,8 +1,8 @@
-// npm edit <pkg>[@<version>]
+// npm edit <pkg>
 // open the package folder in the $EDITOR
 
 module.exports = edit
-edit.usage = "npm edit <pkg>"
+edit.usage = "npm edit <pkg>[@<version>]"
 
 edit.completion = require("./utils/completion/installed-shallow.js")
 
diff --git a/lib/explore.js b/lib/explore.js
index 1a40633ab..452be6d72 100644
--- a/lib/explore.js
+++ b/lib/explore.js
@@ -2,7 +2,7 @@
 // open a subshell to the package folder.
 
 module.exports = explore
-explore.usage = "npm explore <pkg> [ -- <cmd>]"
+explore.usage = 'npm explore <pkg> [ -- <cmd>]'
 explore.completion = require("./utils/completion/installed-shallow.js")
 
 var npm = require("./npm.js")
diff --git a/lib/init.js b/lib/init.js
index ffea8461e..c4fe80735 100644
--- a/lib/init.js
+++ b/lib/init.js
@@ -7,7 +7,7 @@ var log = require("npmlog")
   , npm = require("./npm.js")
   , initJson = require("init-package-json")
 
-init.usage = "npm init [--force/-f]"
+init.usage = "npm init [--force|-f|--yes|-y]"
 
 function init (args, cb) {
   var dir = process.cwd()
diff --git a/lib/install.js b/lib/install.js
index 3bd86f2b2..dcb497470 100644
--- a/lib/install.js
+++ b/lib/install.js
@@ -15,20 +15,18 @@
 module.exports = install
 module.exports.Installer = Installer
 
-install.usage = 'npm install' +
-                '\nnpm install <pkg>' +
-                '\nnpm install <pkg>@<tag>' +
-                '\nnpm install <pkg>@<version>' +
-                '\nnpm install <pkg>@<version range>' +
+install.usage = '\nnpm install (with no args, in package dir)' +
+                '\nnpm install [<@scope>/]<pkg>' +
+                '\nnpm install [<@scope>/]<pkg>@<tag>' +
+                '\nnpm install [<@scope>/]<pkg>@<version>' +
+                '\nnpm install [<@scope>/]<pkg>@<version range>' +
                 '\nnpm install <folder>' +
                 '\nnpm install <tarball file>' +
                 '\nnpm install <tarball url>' +
                 '\nnpm install <git:// url>' +
                 '\nnpm install <github username>/<github project>' +
-                '\n\nCan specify one or more: npm install ./foo.tgz bar@stable /some/folder' +
-                '\nIf no argument is supplied and ./npm-shrinkwrap.json is ' +
-                '\npresent, installs dependencies specified in the shrinkwrap.' +
-                '\nOtherwise, installs dependencies from ./package.json.'
+                '\n\nalias: npm i' +
+                '\ncommon options: [--save|--save-dev|--save-optional] [--save-exact]'
 
 install.completion = function (opts, cb) {
   validate('OF', arguments)
diff --git a/lib/link.js b/lib/link.js
index 4c5622aab..7fe244977 100644
--- a/lib/link.js
+++ b/lib/link.js
@@ -14,7 +14,8 @@ var npm = require("./npm.js")
 module.exports = link
 
 link.usage = "npm link (in package dir)"
-           + "\nnpm link <pkg> (link global into local)"
+           + "\nnpm link [<@scope>/]<pkg>[@<version>]"
+           + "\n\nalias: npm ln"
 
 link.completion = function (opts, cb) {
   var dir = npm.globalDir
diff --git a/lib/logout.js b/lib/logout.js
index 64635be4d..90eb13dd6 100644
--- a/lib/logout.js
+++ b/lib/logout.js
@@ -6,7 +6,7 @@ var log = require("npmlog")
 var npm = require("./npm.js")
 var mapToRegistry = require("./utils/map-to-registry.js")
 
-logout.usage = "npm logout [--registry] [--scope]"
+logout.usage = "npm logout [--registry=<url>] [--scope=<@scope>]"
 
 function logout (args, cb) {
   npm.spinner.start()
diff --git a/lib/ls.js b/lib/ls.js
index 414031ed3..8213bcdc8 100644
--- a/lib/ls.js
+++ b/lib/ls.js
@@ -19,7 +19,8 @@ var npm = require('./npm.js')
 var logicalTree = require('./install/logical-tree.js')
 var recalculateMetadata = require('./install/deps.js').recalculateMetadata
 
-ls.usage = 'npm ls'
+ls.usage = "npm ls [[<@scope>/]<pkg> ...]" +
+    "\n\naliases: list, la, ll"
 
 ls.completion = require('./utils/completion/installed-deep.js')
 
diff --git a/lib/outdated.js b/lib/outdated.js
index 3dcfab69d..8dc4a247d 100644
--- a/lib/outdated.js
+++ b/lib/outdated.js
@@ -16,7 +16,7 @@ packages.
 
 module.exports = outdated
 
-outdated.usage = 'npm outdated [<pkg> [<pkg> ...]]'
+outdated.usage = "npm outdated [[<@scope>/]<pkg> ...]"
 
 outdated.completion = require('./utils/completion/installed-deep.js')
 
diff --git a/lib/owner.js b/lib/owner.js
index c9adb7922..43076d877 100644
--- a/lib/owner.js
+++ b/lib/owner.js
@@ -1,8 +1,8 @@
 module.exports = owner
 
-owner.usage = "npm owner add <username> <pkg>"
-            + "\nnpm owner rm <username> <pkg>"
-            + "\nnpm owner ls <pkg>"
+owner.usage = "npm owner add <user> [<@scope>/]<pkg>"
+            + "\nnpm owner rm <user> [<@scope>/]<pkg>"
+            + "\nnpm owner ls [<@scope>/]<pkg>"
 
 var npm = require("./npm.js")
   , log = require("npmlog")
diff --git a/lib/pack.js b/lib/pack.js
index a5ce90094..1ccbd2e88 100644
--- a/lib/pack.js
+++ b/lib/pack.js
@@ -14,7 +14,7 @@ var npm = require("./npm.js")
   , writeStream = require('fs-write-stream-atomic')
   , cachedPackageRoot = require("./cache/cached-package-root.js")
 
-pack.usage = "npm pack <pkg>"
+pack.usage = "npm pack [[<@scope>/]<pkg>...]"
 
 // if it can be installed, it can be packed.
 pack.completion = install.completion
diff --git a/lib/prefix.js b/lib/prefix.js
index e002edea1..58b2af3a7 100644
--- a/lib/prefix.js
+++ b/lib/prefix.js
@@ -2,7 +2,7 @@ module.exports = prefix
 
 var npm = require("./npm.js")
 
-prefix.usage = "npm prefix\nnpm prefix -g\n(just prints the prefix folder)"
+prefix.usage = "npm prefix [-g]"
 
 function prefix (args, silent, cb) {
   if (typeof cb !== "function") cb = silent, silent = false
diff --git a/lib/prune.js b/lib/prune.js
index edba87601..2f27fdf32 100644
--- a/lib/prune.js
+++ b/lib/prune.js
@@ -2,7 +2,7 @@
 
 module.exports = prune
 
-prune.usage = "npm prune"
+prune.usage = "npm prune [[<@scope>/]<pkg>...] [--production]"
 
 var readInstalled = require("read-installed")
   , npm = require("./npm.js")
diff --git a/lib/publish.js b/lib/publish.js
index 8f1c73c3c..77db8cd43 100644
--- a/lib/publish.js
+++ b/lib/publish.js
@@ -14,8 +14,8 @@ var npm = require("./npm.js")
   , semver = require('semver')
   , getPublishConfig = require("./utils/get-publish-config.js")
 
-publish.usage = "npm publish <tarball> [--tag <tagname>]"
-              + "\nnpm publish <folder> [--tag <tagname>]"
+publish.usage = "npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>]"
+
               + "\n\nPublishes '.' if no argument supplied"
               + "\n\nSets tag `latest` if no --tag specified"
 
diff --git a/lib/rebuild.js b/lib/rebuild.js
index 70c33e91e..53bd95cff 100644
--- a/lib/rebuild.js
+++ b/lib/rebuild.js
@@ -7,7 +7,7 @@ var readInstalled = require("read-installed")
   , npm = require("./npm.js")
   , npa = require("npm-package-arg")
 
-rebuild.usage = "npm rebuild [<name>[@<version>] [name[@<version>] ...]]"
+rebuild.usage = "npm rebuild [[<@scope>/<name>]...]"
 
 rebuild.completion = require("./utils/completion/installed-deep.js")
 
diff --git a/lib/repo.js b/lib/repo.js
index b6c1b2833..bbafaec3c 100644
--- a/lib/repo.js
+++ b/lib/repo.js
@@ -1,6 +1,6 @@
 module.exports = repo
 
-repo.usage = "npm repo <pkgname>"
+repo.usage = "npm repo [<pkg>]"
 
 var npm = require("./npm.js")
   , opener = require("opener")
diff --git a/lib/root.js b/lib/root.js
index b2f731ed5..9310bda92 100644
--- a/lib/root.js
+++ b/lib/root.js
@@ -2,7 +2,7 @@ module.exports = root
 
 var npm = require("./npm.js")
 
-root.usage = "npm root\nnpm root -g\n(just prints the root folder)"
+root.usage = "npm root [-g]"
 
 function root (args, silent, cb) {
   if (typeof cb !== "function") cb = silent, silent = false
diff --git a/lib/run-script.js b/lib/run-script.js
index 057af2bc6..2ca30d0e8 100644
--- a/lib/run-script.js
+++ b/lib/run-script.js
@@ -7,7 +7,8 @@ var lifecycle = require("./utils/lifecycle.js")
   , log = require("npmlog")
   , chain = require("slide").chain
 
-runScript.usage = "npm run-script <command> [-- <args>]"
+runScript.usage = "npm run-script <command> [-- <args>...]"
+    + "\n\nalias: npm run"
 
 runScript.completion = function (opts, cb) {
 
diff --git a/lib/search.js b/lib/search.js
index 840bc2f6b..6dc1c027e 100644
--- a/lib/search.js
+++ b/lib/search.js
@@ -5,7 +5,8 @@ var npm = require("./npm.js")
   , columnify = require("columnify")
   , updateIndex = require("./cache/update-index.js")
 
-search.usage = "npm search [some search terms ...]"
+search.usage = "npm search [--long] [search terms ...]"
+    + "\n\naliases: s, se"
 
 search.completion = function (opts, cb) {
   var compl = {}
diff --git a/lib/star.js b/lib/star.js
index 1f324336c..b6fc49326 100644
--- a/lib/star.js
+++ b/lib/star.js
@@ -6,8 +6,8 @@ var npm = require("./npm.js")
   , asyncMap = require("slide").asyncMap
   , mapToRegistry = require("./utils/map-to-registry.js")
 
-star.usage = "npm star <package> [pkg, pkg, ...]\n"
-           + "npm unstar <package> [pkg, pkg, ...]"
+star.usage = "npm star [<pkg>...]\n"
+           + "npm unstar [<pkg>...]"
 
 star.completion = function (opts, cb) {
   // FIXME: there used to be registry completion here, but it stopped making
diff --git a/lib/stars.js b/lib/stars.js
index 01ec76e42..e8cb23fb4 100644
--- a/lib/stars.js
+++ b/lib/stars.js
@@ -1,6 +1,6 @@
 module.exports = stars
 
-stars.usage = "npm stars [username]"
+gstars.usage = "npm stars [<user>]"
 
 var npm = require("./npm.js")
   , log = require("npmlog")
diff --git a/lib/tag.js b/lib/tag.js
index 75da0b217..24d54676a 100644
--- a/lib/tag.js
+++ b/lib/tag.js
@@ -1,7 +1,8 @@
 // turns out tagging isn't very complicated
 // all the smarts are in the couch.
 module.exports = tag
-tag.usage = "npm tag <project>@<version> [<tag>]"
+tag.usage = "[DEPRECATED] npm tag <name>@<version> [<tag>]"
+          + "\nSee `dist-tag`"
 
 tag.completion = require("./unpublish.js").completion
 
diff --git a/lib/uninstall.js b/lib/uninstall.js
index 500a73242..3106b12e7 100644
--- a/lib/uninstall.js
+++ b/lib/uninstall.js
@@ -4,8 +4,8 @@
 module.exports = uninstall
 module.exports.Uninstaller = Uninstaller
 
-uninstall.usage = 'npm uninstall <name>[@<version> [<name>[@<version>] ...]' +
-                  '\nnpm rm <name>[@<version> [<name>[@<version>] ...]'
+uninstall.usage = 'npm uninstall [<@scope>/]<pkg>[@<version>]... [--save|--save-dev|--save-optional]' +
+                  '\n\naliases: remove, rm, r, un, unlink'
 
 var util = require('util')
 var path = require('path')
diff --git a/lib/unpublish.js b/lib/unpublish.js
index 111f27aa2..c692730a9 100644
--- a/lib/unpublish.js
+++ b/lib/unpublish.js
@@ -9,7 +9,7 @@ var mapToRegistry = require("./utils/map-to-registry.js")
 var npa = require("npm-package-arg")
 var getPublishConfig = require("./utils/get-publish-config.js")
 
-unpublish.usage = "npm unpublish <project>[@<version>]"
+unpublish.usage = "npm unpublish [<@scope>/]<pkg>[@<version>]"
 
 unpublish.completion = function (opts, cb) {
   if (opts.conf.argv.remain.length >= 3) return cb()
diff --git a/lib/update.js b/lib/update.js
index ead9945ed..1d487a6e4 100644
--- a/lib/update.js
+++ b/lib/update.js
@@ -1,6 +1,6 @@
 module.exports = update
 
-update.usage = 'npm update [pkg]'
+update.usage = 'npm update [-g] [<pkg>...]'
 
 var url = require('url')
 var log = require('npmlog')
diff --git a/lib/version.js b/lib/version.js
index f763aad0a..08b276c37 100644
--- a/lib/version.js
+++ b/lib/version.js
@@ -13,7 +13,7 @@ var semver = require("semver")
   , assert = require("assert")
   , lifecycle = require("./utils/lifecycle.js")
 
-version.usage = "npm version [<newversion> | major | minor | patch | prerelease | preminor | premajor ]\n"
+version.usage = "npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]"
               + "\n(run in package dir)\n"
               + "'npm -v' or 'npm --version' to print npm version "
               + "("+npm.version+")\n"
diff --git a/lib/view.js b/lib/view.js
index 9199d352a..45815455b 100644
--- a/lib/view.js
+++ b/lib/view.js
@@ -1,7 +1,8 @@
 // npm view [pkg [pkg ...]]
 
 module.exports = view
-view.usage = "npm view pkg[@version] [<field>[.subfield]...]"
+view.usage = "npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]"
+           + "\n\naliases: info, show, v"
 
 var npm = require("./npm.js")
   , readJson = require("read-package-json")
diff --git a/lib/whoami.js b/lib/whoami.js
index d92a6574a..a3f83cf45 100644
--- a/lib/whoami.js
+++ b/lib/whoami.js
@@ -2,7 +2,7 @@ var npm = require("./npm.js")
 
 module.exports = whoami
 
-whoami.usage = "npm whoami\n(just prints username according to given registry)"
+whoami.usage = "npm whoami [--registry <registry>]\n(just prints username according to given registry)"
 
 function whoami (args, silent, cb) {
   // FIXME: need tighter checking on this, but is a breaking change