refactor(docs): improve cli commands help and description text

garden-service/src/cli/cli.ts

@@ -116,7 +116,7 @@ export const GLOBAL_OPTIONS = {
     choices: logLevelChoices,
     help:
       "Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 " +
-      "(highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5",
+      "(highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5.",
     hints:
       "[enum] [default: info] [error || 0, warn || 1, info || 2, verbose || 3, debug || 4, silly || 5]",
     defaultValue: LogLevel[LogLevel.info],

garden-service/src/commands/base.ts

@@ -162,7 +162,7 @@ export class BooleanParameter extends Parameter<boolean> {
 
 // TODO: maybe this should be a global option?
 export class EnvironmentOption extends StringParameter {
-  constructor({ help = "The environment (and optionally namespace) to work against" } = {}) {
+  constructor({ help = "The environment (and optionally namespace) to work against." } = {}) {
     super({
       help,
       required: false,

garden-service/src/commands/build.ts

@@ -24,7 +24,7 @@ import { hotReloadAndLog } from "./helpers"
 
 const buildArguments = {
   module: new StringsParameter({
-    help: "Specify module(s) to build. Use comma separator to specify multiple modules.",
+    help: "Specify module(s) to build. Use comma as a separator to specify multiple modules.",
   }),
 }
 

garden-service/src/commands/call.ts

@@ -24,7 +24,7 @@ import dedent = require("dedent")
 
 const callArgs = {
   serviceAndPath: new StringParameter({
-    help: "The name of the service(s) to call followed by the ingress path (e.g. my-container/somepath).",
+    help: "The name(s) of the service(s) to call followed by the ingress path (e.g. my-container/somepath).",
     required: true,
   }),
 }
@@ -36,7 +36,7 @@ export class CallCommand extends Command<Args> {
   help = "Call a service ingress endpoint."
 
   description = dedent`
-    This command resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
+    Resolves the deployed ingress endpoint for the given service and path, calls the given endpoint and
     outputs the result.
 
     Examples:

garden-service/src/commands/create/module.ts

@@ -28,7 +28,7 @@ import { ensureDir } from "fs-extra"
 
 const createModuleOptions = {
   name: new StringParameter({
-    help: "Assigns a custom name to the module. (Defaults to name of the current directory.)",
+    help: "Assigns a custom name to the module (defaults to name of the current directory)",
   }),
   type: new ChoicesParameter({
     help: "Type of module.",
@@ -38,7 +38,7 @@ const createModuleOptions = {
 
 const createModuleArguments = {
   "module-dir": new StringParameter({
-    help: "Directory of the module. (Defaults to current directory.)",
+    help: "Directory of the module (defaults to current directory).",
   }),
 }
 
@@ -56,8 +56,6 @@ export class CreateModuleCommand extends Command<Args, Opts> {
   help = "Creates a new Garden module."
 
   description = dedent`
-    Creates a new Garden module of the given type
-
     Examples:
 
         garden create module # creates a new module in the current directory (module name defaults to directory name)

garden-service/src/commands/create/project.ts

@@ -37,16 +37,16 @@ import { projectSchema } from "../../config/project"
 
 const createProjectOptions = {
   "module-dirs": new PathsParameter({
-    help: "Relative path to modules directory. Use comma as a separator to specify multiple directories",
+    help: "Relative path to modules directory. Use comma as a separator to specify multiple directories.",
   }),
   name: new StringParameter({
-    help: "Assigns a custom name to the project. (Defaults to name of the current directory.)",
+    help: "Assigns a custom name to the project (defaults to name of the current directory).",
   }),
 }
 
 const createProjectArguments = {
   "project-dir": new StringParameter({
-    help: "Directory of the project. (Defaults to current directory.)",
+    help: "Directory of the project (defaults to current directory).",
   }),
 }
 
@@ -67,16 +67,16 @@ export class CreateProjectCommand extends Command<Args, Opts> {
   help = "Creates a new Garden project."
 
   description = dedent`
-    The 'create project' command walks the user through setting up a new Garden project and
+    Walks the user through setting up a new Garden project and
     generates scaffolding based on user input.
 
     Examples:
 
         garden create project # creates a new Garden project in the current directory (project name defaults to
         directory name)
         garden create project my-project # creates a new Garden project in my-project directory
-        garden create project --module-dirs=path/to/modules1,path/to/modules2
-        # creates a new Garden project and looks for pre-existing modules in the modules1 and modules2 directories
+        garden create project --module-dirs=path/to/modules-a,path/to/modules-b
+        # creates a new Garden project and looks for pre-existing modules in the modules-a and modules-b directories
         garden create project --name my-project
         # creates a new Garden project in the current directory and names it my-project
   `

garden-service/src/commands/delete.ts

@@ -105,7 +105,7 @@ export class DeleteEnvironmentCommand extends Command {
 
 const deleteServiceArgs = {
   service: new StringsParameter({
-    help: "The name of the service(s) to delete. Use comma as separator to specify multiple services.",
+    help: "The name(s) of the service(s) to delete. Use comma as a separator to specify multiple services.",
     required: true,
   }),
 }

garden-service/src/commands/deploy.ts

@@ -7,6 +7,8 @@
  */
 
 import deline = require("deline")
+import dedent = require("dedent")
+
 import {
   BooleanParameter,
   Command,
@@ -24,7 +26,7 @@ import { getNames } from "../util/util"
 const deployArgs = {
   service: new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy (skip to deploy all services).
-      Use comma as separator to specify multiple services.`,
+      Use comma as a separator to specify multiple services.`,
   }),
 }
 
@@ -34,7 +36,7 @@ const deployOpts = {
   watch: new BooleanParameter({ help: "Watch for changes in module(s) and auto-deploy.", alias: "w" }),
   "hot-reload": new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy with hot reloading enabled.
-      Use comma as separator to specify multiple services. When this option is used,
+      Use comma as a separator to specify multiple services. When this option is used,
       the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag).
     `,
   }),
@@ -47,7 +49,7 @@ export class DeployCommand extends Command<Args, Opts> {
   name = "deploy"
   help = "Deploy service(s) to your environment."
 
-  description = `
+  description = dedent`
     Deploys all or specified services, taking into account service dependency order.
     Also builds modules and dependencies if needed.
 

garden-service/src/commands/dev.ts

@@ -8,6 +8,7 @@
 
 import * as Bluebird from "bluebird"
 import deline = require("deline")
+import dedent = require("dedent")
 import chalk from "chalk"
 import { readFile } from "fs-extra"
 import { flatten } from "lodash"
@@ -38,7 +39,7 @@ const devArgs = {}
 const devOpts = {
   "hot-reload": new StringsParameter({
     help: deline`The name(s) of the service(s) to deploy with hot reloading enabled.
-      Use comma as separator to specify multiple services.
+      Use comma as a separator to specify multiple services.
     `}),
 }
 
@@ -50,7 +51,7 @@ export class DevCommand extends Command<Args, Opts> {
   name = "dev"
   help = "Starts the garden development console."
 
-  description = `
+  description = dedent`
     The Garden dev console is a combination of the \`build\`, \`deploy\` and \`test\` commands.
     It builds, deploys and tests all your modules and services, and re-builds, re-deploys and re-tests
     as you modify the code.

garden-service/src/commands/link/module.ts

@@ -47,7 +47,7 @@ export class LinkModuleCommand extends Command<Args> {
   description = dedent`
     After linking a remote module, Garden will read the source from the module's local directory instead of from
     the remote URL. Garden can only link modules that have a remote source,
-    i.e. modules that specifiy a repositoryUrl in their garden.yml config file.
+    i.e. modules that specifiy a \`repositoryUrl\` in their \`garden.yml\` config file.
 
     Examples:
 

garden-service/src/commands/link/source.ts

@@ -42,7 +42,7 @@ export class LinkSourceCommand extends Command<Args> {
   description = dedent`
     After linking a remote source, Garden will read it from its local directory instead of
     from the remote URL. Garden can only link remote sources that have been declared in the project
-    level garden.yml config.
+    level \`garden.yml\` config.
 
     Examples:
 

garden-service/src/commands/logs.ts

@@ -23,8 +23,8 @@ import dedent = require("dedent")
 
 const logsArgs = {
   service: new StringsParameter({
-    help: "The name of the service(s) to logs (skip to logs all services). " +
-      "Use comma as separator to specify multiple services.",
+    help: "The name(s) of the service(s) to log (skip to log all services). " +
+      "Use comma as a separator to specify multiple services.",
   }),
 }
 

garden-service/src/commands/publish.ts

@@ -23,8 +23,8 @@ import dedent = require("dedent")
 
 const publishArgs = {
   module: new StringsParameter({
-    help: "The name of the module(s) to publish (skip to publish all modules). " +
-      "Use comma as separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to publish (skip to publish all modules). " +
+      "Use comma as a separator to specify multiple modules.",
   }),
 }
 

garden-service/src/commands/run/service.ts

@@ -22,21 +22,21 @@ import { prepareRuntimeContext } from "../../types/service"
 
 const runArgs = {
   service: new StringParameter({
-    help: "The service to run",
+    help: "The service to run.",
     required: true,
   }),
 }
 
 const runOpts = {
-  "force-build": new BooleanParameter({ help: "Force rebuild of module" }),
+  "force-build": new BooleanParameter({ help: "Force rebuild of module." }),
 }
 
 type Args = typeof runArgs
 type Opts = typeof runOpts
 
 export class RunServiceCommand extends Command<Args, Opts> {
   name = "service"
-  help = "Run an ad-hoc instance of the specified service"
+  help = "Run an ad-hoc instance of the specified service."
 
   description = dedent`
     This can be useful for debugging or ad-hoc experimentation with services.

garden-service/src/commands/test.ts

@@ -8,6 +8,8 @@
 
 import * as Bluebird from "bluebird"
 import { flatten } from "lodash"
+import dedent = require("dedent")
+
 import {
   BooleanParameter,
   Command,
@@ -25,8 +27,8 @@ import { computeAutoReloadDependants, withDependants } from "../watch"
 
 const testArgs = {
   module: new StringsParameter({
-    help: "The name of the module(s) to deploy (skip to test all modules). " +
-      "Use comma as separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to test (skip to test all modules). " +
+      "Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -47,20 +49,20 @@ export class TestCommand extends Command<Args, Opts> {
   name = "test"
   help = "Test all or specified modules."
 
-  description = `
+  description = dedent`
     Runs all or specified tests defined in the project. Also builds modules and dependencies,
-    and deploy service dependencies if needed.
+    and deploys service dependencies if needed.
 
     Optionally stays running and automatically re-runs tests if their module source
     (or their dependencies' sources) change.
 
     Examples:
 
-        garden test              # run all tests in the project
-        garden test my-module    # run all tests in the my-module module
-        garden test -n integ     # run all tests with the name 'integ' in the project
-        garden test --force      # force tests to be re-run, even if they're already run successfully
-        garden test --watch      # watch for changes to code
+        garden test               # run all tests in the project
+        garden test my-module     # run all tests in the my-module module
+        garden test --name integ  # run all tests with the name 'integ' in the project
+        garden test --force       # force tests to be re-run, even if they've already run successfully
+        garden test --watch       # watch for changes to code
   `
 
   arguments = testArgs

garden-service/src/commands/unlink/module.ts

@@ -23,7 +23,7 @@ import {
 
 const unlinkModuleArguments = {
   module: new StringsParameter({
-    help: "Name of the module(s) to unlink. Use comma separator to specify multiple modules.",
+    help: "The name(s) of the module(s) to unlink. Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -49,8 +49,8 @@ export class UnlinkModuleCommand extends Command<Args, Opts> {
 
     Examples:
 
-        garden unlink module my-module # unlinks my-module
-        garden unlink module --all # unlink all modules
+        garden unlink module my-module  # unlinks my-module
+        garden unlink module --all      # unlink all modules
   `
 
   async action({ garden, args, opts }: CommandParams<Args, Opts>): Promise<CommandResult<LinkedSource[]>> {

garden-service/src/commands/unlink/source.ts

@@ -23,7 +23,7 @@ import {
 
 const unlinkSourceArguments = {
   source: new StringsParameter({
-    help: "Name of the source(s) to unlink. Use comma separator to specify multiple sources.",
+    help: "The name(s) of the source(s) to unlink. Use comma as a separator to specify multiple sources.",
   }),
 }
 
@@ -49,8 +49,8 @@ export class UnlinkSourceCommand extends Command<Args, Opts> {
 
     Examples:
 
-        garden unlink source my-source # unlinks my-source
-        garden unlink source --all # unlinks all sources
+        garden unlink source my-source  # unlinks my-source
+        garden unlink source --all      # unlinks all sources
   `
 
   async action({ garden, args, opts }: CommandParams<Args, Opts>): Promise<CommandResult<LinkedSource[]>> {

garden-service/src/commands/update-remote/modules.ts

@@ -23,7 +23,7 @@ import { hasRemoteSource } from "../../util/ext-source-util"
 
 const updateRemoteModulesArguments = {
   module: new StringsParameter({
-    help: "Name of the remote module(s) to update. Use comma separator to specify multiple modules.",
+    help: "The name(s) of the remote module(s) to update. Use comma as a separator to specify multiple modules.",
   }),
 }
 
@@ -35,8 +35,8 @@ export class UpdateRemoteModulesCommand extends Command<Args> {
   arguments = updateRemoteModulesArguments
 
   description = dedent`
-    Remote modules are modules that have a repositoryUrl field
-    in their garden.yml config that points to a remote repository.
+    Updates remote modules, i.e. modules that have a \`repositoryUrl\` field
+    in their \`garden.yml\` config that points to a remote repository.
 
     Examples:
 

garden-service/src/commands/update-remote/sources.ts

@@ -22,7 +22,7 @@ import { SourceConfig } from "../../config/project"
 
 const updateRemoteSourcesArguments = {
   source: new StringsParameter({
-    help: "Name of the remote source(s) to update. Use comma separator to specify multiple sources.",
+    help: "The name(s) of the remote source(s) to update. Use comma as a separator to specify multiple sources.",
   }),
 }
 
@@ -34,11 +34,11 @@ export class UpdateRemoteSourcesCommand extends Command<Args> {
   arguments = updateRemoteSourcesArguments
 
   description = dedent`
-    Update the remote sources declared in the project config.
+    Updates the remote sources declared in the project level \`garden.yml\` config file.
 
     Examples:
 
-        garden update-remote sources            # update all remote sources in the project config
+        garden update-remote sources            # update all remote sources
         garden update-remote sources my-source  # update remote source my-source
   `
 

garden-service/src/docs/templates/commands.hbs

@@ -2,7 +2,7 @@
 
 Below is a list of Garden CLI commands and usage information.
 
-The commands should be run in a Garden project root, and are always scoped to that project.
+The commands should be run in a Garden project, and are always scoped to that project.
 
 Note: You can get a list of commands in the CLI by running `garden -h/--help`,
 and detailed help for each command using `garden <command> -h/--help`