bolt 3.7.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575cccb1487a82a6537a83d5d23a89d9e3ed44898af25e2fe34acda2ecd765ae
-  data.tar.gz: a9de53717fdcb5380f95ef5ee1fb26b3d28eaa59f92355d9558954d14192f307
+  metadata.gz: 741f798df2b4c7a46e45c5c87a41cd4e994506cdd202d26b6acafae7774135f8
+  data.tar.gz: 803789a5f6872e27656a733e94998acc9dde4d325d2d920b345a1c2848683f2f
 SHA512:
-  metadata.gz: 60378d6872763f5fb557deae88207c29db0626d90562e37d80df1f604368629049da79ff0a0216602057566c7eb10892855f33a99b03bfc348fce8b443e7682d
-  data.tar.gz: e2f8dd460e346648e53921e299db5b7beaf4ba1a0cd7efe95728e2e2d42c3e4b3624c40ef8a94a21b7e4be5003d67a1a64c48d1a36a9e314c4d7bb296ce85eab
+  metadata.gz: 85cb83b0a0bf02d1ba15b14ba5e5e75c6ff290e1acee71b0de06ea716f3698e91358aa6f9961757b088afa3c98d519ba10f79a6195c767492a87603759c2fc81
+  data.tar.gz: 8180f0827c3576e676e6fca59af7744d3e375023b44c0ebc2e691801a25f8fc1cac2487276661f7b40503e8ab1164ae07ee5f8343be9bb5be3088851e81eafaf

data/bolt-modules/boltlib/lib/puppet/datatypes/applyresult.rb

@@ -1,5 +1,31 @@
 # frozen_string_literal: true
 
+# An [apply action](applying_manifest_blocks.md#return-value-of-apply-action)
+# returns an `ApplyResult`. An `ApplyResult` is part of a `ResultSet` object and
+# contains information about the apply action.
+#
+# @param report
+#   The Puppet report from the apply action. Equivalent to calling `ApplyResult.value['report']`.
+#   The report is a hash representation of the [`Puppet::Transaction::Report`
+#   object](https://puppet.com/docs/puppet/latest/format_report.html), where each property
+#   corresponds to a key in the report hash. For more information, see [Result
+#   keys](applying_manifest_blocks.md#result-keys).
+# @param target
+#   The target the result is from.
+#
+# @!method action
+#   The action performed. `ApplyResult.action` always returns the string `apply`.
+# @!method error
+#   Returns an Error object constructed from the `_error` field of the result's value.
+# @!method message
+#   The `_output` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method to_data
+#   A serialized representation of `ApplyResult`.
+# @!method value
+#   A hash including the Puppet report from the apply action under a `report` key.
+#
 Puppet::DataTypes.create_type('ApplyResult') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/containerresult.rb

@@ -1,5 +1,32 @@
 # frozen_string_literal: true
 
+# The [run_container](plan_functions.md#run_container) plan function returns a
+# `ContainerResult` object. A `ContainerResult` is a standalone object (not part
+# of a `ResultSet`) that includes either the `stdout` and `stderr` values from
+# running the container, or an `_error` object if the container exited with a
+# nonzero exit code.
+#
+# @param value
+#   A hash including the `stdout`, `stderr`, and `exit_code` received from the
+#   container.
+#
+# @!method []
+#   Accesses the value hash directly and returns the value for the key. This
+#   function does not use dot notation. Call the function directly on the
+#   `ContainerResult`. For example, `$result[key]`.
+# @!method error
+#   An object constructed from the `_error` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method status
+#   Either `success` if the result was successful or `failure`.
+# @!method stdout
+#   The value of 'stdout' output by the container.
+# @!method stderr
+#   The value of 'stderr' output by the container.
+# @!method to_data
+#   A serialized representation of `ContainerResult`.
+#
 Puppet::DataTypes.create_type('ContainerResult') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/resourceinstance.rb

@@ -1,5 +1,48 @@
 # frozen_string_literal: true
 
+# `ResourceInstance` objects are used to store the observed and desired state of a
+# target's resource and to track events for the resource. These objects do not
+# modify or interact with a target's resources.
+#
+# > The `ResourceInstance` data type is experimental and might change in a future
+# > release. You can learn more about this data type and how to use it in the
+# > [experimental features
+# > documentation](experimental_features.md#resourceinstance-data-type).
+#
+# @param events
+#   Events for the resource.
+# @param desired_state
+#   [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
+#   the desired state of the resource.
+# @param state
+#   [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
+#   the observed state of the resource.
+# @param target
+#   The resource's target.
+# @param title
+#   The [resource title](https://puppet.com/docs/puppet/latest/lang_resources.html#title).
+# @param type
+#   The [resource type](https://puppet.com/docs/puppet/latest/lang_resources.html#resource-types).
+#
+# @!method []
+#   Accesses the `state` hash directly and returns the value for the specified
+#   attribute. This function does not use dot noation. Call the function directly
+#   on the `ResourceInstance`. For example, `$resource['ensure']`.
+# @!method add_event(event)
+#   Add an event for the resource.
+# @!method overwrite_desired_state(desired_state)
+#   Overwrites the desired state of the resource.
+# @!method overwrite_state(state)
+#   Overwrites the observed state of the resource.
+# @!method set_desired_state(desired_state)
+#   Sets attributes describing the desired state of the resource. Performs a shallow
+#   merge with existing desired state.
+# @!method set_state(state)
+#   Sets attributes describing the observed state of the resource. Performs a shallow
+#   merge with existing state.
+# @!method reference
+#   The resources reference string. For example, `File[/etc/puppetlabs]`.
+#
 Puppet::DataTypes.create_type('ResourceInstance') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/result.rb

@@ -1,5 +1,34 @@
 # frozen_string_literal: true
 
+# For each target that you execute an action on, Bolt returns a `Result` object
+# and adds the `Result` to a `ResultSet` object. A `Result` object contains
+# information about the action you executed on the target.
+#
+# @param target
+#   The target the result is from.
+# @param value
+#   The output or return of executing on the target.
+#
+# @!method []
+#   Accesses the `value` hash directly and returns the value for the key. This
+#   function does not use dot nation. Call the function directly on the `Result`.
+#   For example, `$result['key']`.
+# @!method action
+#   The type of result. For example, `task` or `command`.
+# @!method error
+#   An object constructed from the `_error` field of the result's `value`.
+# @!method message
+#   The `_output` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method sensitive
+#   The `_sensitive` field of the result's value, wrapped in a `Sensitive` object.
+#   Call `unwrap()` to extract the value.
+# @!method status
+#   Either `success` if the result was successful or `failure`.
+# @!method to_data
+#   A serialized representation of `Result`.
+#
 Puppet::DataTypes.create_type('Result') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/resultset.rb

@@ -1,5 +1,39 @@
 # frozen_string_literal: true
 
+# For each target that you execute an action on, Bolt returns a `Result` object
+# and adds the `Result` to a `ResultSet` object. In the case of [apply
+# actions](applying_manifest_blocks.md), Bolt returns a `ResultSet` with one or
+# more `ApplyResult` objects.
+#
+# @param results
+#   All results in the set.
+#
+# @!method []
+#   The accessed results. This function does not use dot notation. Call the
+#   function directly on the `ResultSet`. For example, `$results[0]`.
+# @!method count
+#   The number of results in the set.
+# @!method empty
+#   Whether the set is empty.
+# @!method error_set
+#   The set of failing results.
+# @!method filter_set
+#   Filters a set of results by the contents of the block.
+# @!method find(target_name)
+#   Retrieves a result for a specified target.
+# @!method first
+#   The first result in the set. Useful for unwrapping single results.
+# @!method names
+#   The names of all targets that have a `Result` in the set.
+# @!method ok
+#   Whether all results were successful. Equivalent to `$results.error_set.empty`.
+# @!method ok_set
+#   The set of successful results.
+# @!method targets
+#   The list of targets that have results in the set.
+# @!method to_data
+#   An array of serialized representations of each result in the set.
+#
 Puppet::DataTypes.create_type('ResultSet') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/target.rb

@@ -1,5 +1,60 @@
 # frozen_string_literal: true
 
+# The `Target` object represents a target and its specific connection options.
+#
+# @param config
+#   The inventory configuration for the target. This function returns the
+#   configuration set directly on the target in `inventory.yaml` or set in
+#   a plan using `Target.new` or `set_config()`. It does not return default
+#   configuration values or configuration set in Bolt configuration files.
+# @param facts
+#   The target's facts. This function does not look up facts for a target and
+#   only returns the facts specified in an `inventory.yaml` file or set on a
+#   target during a plan run. To retrieve facts for a target and set them in
+#   inventory, run the [facts](writing_plans.md#collect-facts-from-targets)
+#   plan or [puppetdb_fact](writing_plans.md#collect-facts-from-puppetdb)
+#   plan.
+# @param features
+#   The target's features.
+# @param name
+#   The target's human-readable name, or its URI if a name was not given.
+# @param plugin_hooks
+#   The target's `plugin_hooks` [configuration
+#   options](bolt_inventory_reference.md#plugin-hooks-1).
+# @param resources
+#   The target's resources. This function does not look up resources for a
+#   target and only returns resources set on a target during a plan run.
+# @param safe_name
+#   The target's safe name. Equivalent to `name` if a name was given, or the
+#   target's `uri` with any password omitted.
+# @param target_alias
+#   The target's aliases.
+# @param uri
+#   The target's URI.
+# @param vars
+#   The target's variables.
+#
+# @!method host
+#   The target's hostname.
+# @!method password
+#   The password to use when connecting to the target.
+# @!method port
+#   The target's connection port.
+# @!method protocol
+#   The protocol used to connect to the target. This is equivalent to the target's
+#   `transport`, expect for targets using the `remote` transport. For example,
+#   a target with the URI `http://example.com` using the `remote` transport would
+#   return `http` for the `protocol`.
+# @!method transport
+#   The transport used to connect to the target.
+# @!method transport_config
+#   The merged configuration for the target's `transport`. This function returns
+#   configuration that includes defaults set by Bolt, configuration set in
+#   `inventory.yaml`, configuration set in `bolt-defaults.yaml`, and configuration
+#   set in a plan using `set_config()`.
+# @!method user
+#   The user to connect to the target.
+#
 Puppet::DataTypes.create_type('Target') do
   begin
     inventory = Puppet.lookup(:bolt_inventory)

data/bolt-modules/boltlib/lib/puppet/functions/add_to_group.rb

@@ -8,6 +8,7 @@ require 'bolt/error'
 Puppet::Functions.create_function(:add_to_group) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param group The name of the group to add targets to.
+  # @return [Array[Target]] The targets.
   # @example Add new Target to group.
   #   Target.new('foo@example.com', 'password' => 'secret').add_to_group('group1')
   # @example Add new target to group by name.

data/bolt-modules/boltlib/lib/puppet/functions/apply_prep.rb

@@ -16,6 +16,7 @@ Puppet::Functions.create_function(:apply_prep) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param options Options hash.
   # @option options [Array] _required_modules An array of modules to sync to the target.
+  # @return [nil]
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
   dispatch :apply_prep do

data/bolt-modules/boltlib/lib/puppet/functions/parallelize.rb

@@ -10,6 +10,7 @@ Puppet::Functions.create_function(:parallelize, Puppet::Functions::InternalFunct
   # Map a block onto an array, where each array element executes in parallel.
   # This function is experimental.
   # @param data The array to apply the block to.
+  # @param block The code block to execute for each array element.
   # @return [Array] An array of PlanResult objects. Each input from the input
   #   array returns a corresponding PlanResult object.
   # @example Execute two tasks on two targets.

data/bolt-modules/boltlib/lib/puppet/functions/remove_from_group.rb

@@ -11,6 +11,7 @@ require 'bolt/error'
 Puppet::Functions.create_function(:remove_from_group) do
   # @param target A pattern identifying a single target.
   # @param group The name of the group to remove the target from.
+  # @return [nil]
   # @example Remove Target from group.
   #   remove_from_group('foo@example.com', 'group1')
   # @example Remove failing Targets from the rest of a plan

data/bolt-modules/boltlib/lib/puppet/functions/write_file.rb

@@ -9,6 +9,7 @@ Puppet::Functions.create_function(:write_file) do
   # @param content File content to write.
   # @param destination An absolute path on the target(s).
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
   # @return A list of results, one entry per target.

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -3,8 +3,10 @@
 # Repeat the block until it returns a truthy value. Returns the value.
 Puppet::Functions.create_function(:'ctrl::do_until') do
   # @param options A hash of additional options.
+  # @param block The code block to repeat.
   # @option options [Numeric] limit The number of times to repeat the block.
   # @option options [Numeric] interval The number of seconds to wait before repeating the block.
+  # @return [nil]
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
   #     run_task('test', $target, '_catch_errors' => true).ok()

data/guides/guide.txt

@@ -0,0 +1,17 @@
+TOPIC
+    guide
+
+DESCRIPTION
+    A guide is a person (or CLI tool ;D) who leads travelers through unknown or
+    unfamiliar locations. The term can also be applied to a person who leads others
+    to more abstract goals such as knowledge or wisdom. 
+
+    Etymology: Originated sometime between 1325 and 1375. From Middle English
+    guide, from the Old French guide, from Old Occitan guida, from guidar, from
+    Frankish *wītan (“to show the way, lead”), from Proto-Germanic *wītaną (“to
+    see, know; go, depart”), from Proto-Indo-European *weyd- (“to see, know”).
+    Related also to English wit. 
+
+DOCUMENTATION
+    https://en.wikipedia.org/wiki/Guide
+    https://en.wiktionary.org/wiki/guide

data/guides/links.txt

@@ -0,0 +1,13 @@
+TOPIC
+    links
+
+DESCRIPTION
+    Bolt documentation          https://bolt.guide
+    Ask a question in #bolt     https://slack.puppet.com/
+    Contribute at               https://github.com/puppetlabs/bolt/
+    Getting Started Guide       https://pup.pt/bolt-getting-started
+    Reference Documentation     https://pup.pt/bolt-reference
+    Troubleshooting Bolt        https://pup.pt/bolt-troubleshooting
+    Bolt Developer Updates      https://pup.pt/bolt-dev-updates
+    Bolt Changelog              https://pup.pt/bolt-changelog
+    Bolt Examples               https://pup.pt/bolt-examples

data/guides/targets.txt

@@ -6,26 +6,24 @@ DESCRIPTION
     be physical, such as servers, or virtual, such as containers or virtual
     machines.
 
-    Several of Bolt's commands connect to targets and run actions on them. When
-    you run these commands, Bolt requires a list of targets to run the action
-    on. For example, the `bolt script run` command and `Invoke-BoltScript`
-    PowerShell cmdlet require you to provide a list of targets to run your
-    script on. You can provide a list of targets to a command using one of the
-    following command-line options:
+    Several of Bolt's commands connect to targets and run actions on them.
+    These commands require a target or targets to run on. You can specify
+    targets to a command using one of the following command-line options:
 
-    Shell commands
-        -t, --targets TARGETS
-        -q, --query   QUERY
-            --rerun   FILTER
+    *nix options                Powershell options
+     -t, --targets TARGETS      -T, -Targets  TARGETS
+     -q, --query   QUERY        -Q, -Query    QUERY
+         --rerun   FILTER       -Rerun        FILTER
 
-    PowerShell cmdlets
-        -T, -Targets TARGETS
-        -Q, -Query   QUERY
-            -Rerun   FILTER
+    The 'targets' option accepts a comma-separated list of target URIs or group
+    names, or can read a target list from an input file '@<file>' or stdin '-'.
+    URIs can be specified with the format [protocol://][user@]host[:port]. To
+    learn more about available protocols and their defaults, run 'bolt guide
+    transports'.
 
     Typically, targets and their configuration and data are listed in a
     project's inventory file. For more information about inventory files,
     see 'bolt guide inventory'.
 
 DOCUMENTATION
-    https://pup.pt/bolt-commands
+    https://pup.pt/bolt-commands

data/guides/transports.txt

@@ -0,0 +1,23 @@
+TOPIC
+    transports
+
+DESCRIPTION
+    Bolt uses transports (also known as protocols) to establish a connection
+    with a target in order to run actions on the target. The default transport is
+    SSH, and you can see available transports along with their configuration
+    options and defaults at http://pup.pt/bolt-reference.
+
+    You can specify a transport for a target by prepending '<transport>://' to
+    the target's URI. For example, to connect to a target with hostname
+    'example.com' as user 'Administrator' using the WinRM transport, you would
+    pass the following to the target flag:
+        winrm://Administrator@example.com
+
+    You can also specify a default transport for all targets by passing the
+    '--transport' flag on *nix systems and the '-Transport' flag in Powershell.
+    Finally, you can set the transport for a target in the inventory. For more
+    information about the Bolt inventory, run 'bolt guide inventory'.
+
+DOCUMENTATION
+    https://pup.pt/bolt-commands#specify-a-transport
+    http://pup.pt/bolt-inventory#transport-configuration

data/lib/bolt/bolt_option_parser.rb

@@ -156,18 +156,30 @@ module Bolt
       end
     end
 
+    COLORS = {
+      cyan: "36"
+    }.freeze
+
+    def self.colorize(color, string)
+      if $stdout.isatty
+        "\033[#{COLORS[color]}m#{string}\033[0m"
+      else
+        string
+      end
+    end
+
     BANNER = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           bolt
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt <subcommand> [action] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Bolt is an orchestration tool that automates the manual work it takes to
           maintain your infrastructure.
 
-      SUBCOMMANDS
+      #{colorize(:cyan, 'Subcommands')}
           apply             Apply Puppet manifest code
           command           Run a command remotely
           file              Copy files between the controller and targets
@@ -181,79 +193,92 @@ module Bolt
           secret            Create encryption keys and encrypt and decrypt values
           task              Show and run Bolt tasks
 
-      GUIDES
+      #{colorize(:cyan, 'Guides')}
           For a list of guides on Bolt's concepts and features, run 'bolt guide'.
+          Find Bolt's documentation at https://bolt.guide.
     HELP
 
     APPLY_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           apply
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt apply [manifest] {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Apply Puppet manifest code on the specified targets.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-apply.
+
+      #{colorize(:cyan, 'Examples')}
           bolt apply manifest.pp -t target
           bolt apply -e "file { '/etc/puppetlabs': ensure => present }" -t target
     HELP
 
     COMMAND_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           command
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt command <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a command on the specified targets.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Actions')}
           run         Run a command on the specified targets.
     HELP
 
     COMMAND_RUN_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           run
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt command run <command> {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a command on the specified targets.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Examples')}
           bolt command run 'uptime' -t target1,target2
     HELP
 
     FILE_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           file
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt file <action> [options]
 
-      DESCRIPTION
-          Copy files and directories between the controller and targets
+      #{colorize(:cyan, 'Description')}
+          Copy files and directories between the controller and targets.
+
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-commands.
 
-      ACTIONS
+      #{colorize(:cyan, 'Actions')}
           download      Download a file or directory to the controller
           upload        Upload a local file or directory from the controller
     HELP
 
     FILE_DOWNLOAD_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           download
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt file download <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Download a file or directory from one or more targets.
 
           Downloaded files and directories are saved to the a subdirectory
@@ -261,64 +286,76 @@ module Bolt
           destination directory is expanded relative to the downloads
           subdirectory of the project directory.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Examples')}
           bolt file download /etc/ssh_config ssh_config -t all
     HELP
 
     FILE_UPLOAD_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           upload
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt file upload <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Upload a local file or directory.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          For documentation see http://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Examples')}
           bolt file upload /tmp/source /etc/profile.d/login.sh -t target1
     HELP
 
     GROUP_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           group
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt group <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show the list of groups in the inventory.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about the inventory run 'bolt guide inventory'.
+
+      #{colorize(:cyan, 'Actions')}
           show          Show the list of groups in the inventory
     HELP
 
     GROUP_SHOW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           show
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt group show [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show the list of groups in the inventory.
+
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about the inventory run 'bolt guide inventory'.
     HELP
 
     GUIDE_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           guide
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt guide [topic] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           View guides for Bolt's concepts and features.
 
           Omitting a topic will display a list of available guides,
           while providing a topic will display the relevant guide.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Examples')}
           View a list of available guides
             bolt guide
           View the 'project' guide page
@@ -326,49 +363,55 @@ module Bolt
     HELP
 
     INVENTORY_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           inventory
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt inventory <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show the list of targets an action would run on.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about the inventory run 'bolt guide inventory'.
+
+      #{colorize(:cyan, 'Actions')}
           show          Show the list of targets an action would run on
     HELP
 
     INVENTORY_SHOW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           show
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt inventory show [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show the list of targets an action would run on. This command will list
           all targets in the project's inventory by default.
 
           To filter the targets in the list, use the --targets, --query, or --rerun
           options. To view detailed configuration and data for targets, use the
-          --detail option.
+          --detail option. To learn more about the inventory run 'bolt guide inventory'.
+
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about the inventory run 'bolt guide inventory'.
     HELP
 
     MODULE_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           module
       
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt module <action> [options]
 
-      DESCRIPTION
-          Manage Bolt project modules
+      #{colorize(:cyan, 'Description')}
+          Manage Bolt project modules.
 
-          The module command is only supported when a project is configured
-          with the 'modules' key.
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt modules run 'bolt guide module'.
 
-      ACTIONS
+      #{colorize(:cyan, 'Actions')}
           add                   Add a module to the project
           generate-types        Generate type references to register in plans
           install               Install the project's modules
@@ -376,77 +419,84 @@ module Bolt
     HELP
 
     MODULE_ADD_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           add
       
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt module add <module> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Add a module to the project.
 
           Module declarations are loaded from the project's configuration
           file. Bolt will automatically resolve all module dependencies,
           generate a Puppetfile, and install the modules.
 
-          The module command is only supported when a project is configured
-          with the 'modules' key.
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt modules, run 'bolt guide module'.
     HELP
 
     MODULE_GENERATETYPES_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           generate-types
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt module generate-types [options]
 
-      DESCRIPTION
-          Generate type references to register in plans.
+      #{colorize(:cyan, 'Description')}
+          Generate type references to register in plans. To learn more about
+          Bolt modules, run 'bolt guide module'.
 
-          The module command is only supported when a project is configured
-          with the 'modules' key.
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt modules, run 'bolt guide module'.
     HELP
 
     MODULE_INSTALL_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           install
       
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt module install [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Install the project's modules.
 
           Module declarations are loaded from the project's configuration
           file. Bolt will automatically resolve all module dependencies,
           generate a Puppetfile, and install the modules.
+
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt modules, run 'bolt guide module'.
     HELP
 
     MODULE_SHOW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           show
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt module show [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           List modules available to the Bolt project.
 
-          The module command is only supported when a project is configured
-          with the 'modules' key.
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt modules, run 'bolt guide module'.
     HELP
 
     PLAN_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           plan
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt plan <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Convert, create, show, and run Bolt plans.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plans at https://pup.pt/bolt-plans.
+
+      #{colorize(:cyan, 'Actions')}
           convert       Convert a YAML plan to a Bolt plan
           new           Create a new plan in the current project
           run           Run a plan on the specified targets
@@ -454,13 +504,13 @@ module Bolt
     HELP
 
     PLAN_CONVERT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           convert
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt plan convert <plan name> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Convert a YAML plan to a Puppet language plan and print the converted
           plan to stdout.
 
@@ -468,47 +518,56 @@ module Bolt
           correct but has different behavior. Always verify a converted plan's
           functionality. Note that the converted plan is not written to a file.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plans at https://pup.pt/bolt-plans.
+
+      #{colorize(:cyan, 'Examples')}
           bolt plan convert myproject::myplan
           bolt plan convert path/to/plan/myplan.yaml
     HELP
 
     PLAN_NEW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           new
       
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt plan new <plan name> [options]
       
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Create a new plan in the current project.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plans at https://pup.pt/bolt-plans.
+
+      #{colorize(:cyan, 'Examples')}
           bolt plan new myproject::myplan
     HELP
 
     PLAN_RUN_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           run
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt plan run <plan name> [parameters] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a plan on the specified targets.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plans at https://pup.pt/bolt-plans.
+
+      #{colorize(:cyan, 'Examples')}
           bolt plan run canary --targets target1,target2 command=hostname
     HELP
 
     PLAN_SHOW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           show
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt plan show [plan name] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show available plans and plan documentation.
 
           Omitting the name of a plan will display a list of plans available
@@ -517,7 +576,10 @@ module Bolt
           Providing the name of a plan will display detailed documentation for
           the plan, including a list of available parameters.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt plans at https://pup.pt/bolt-plans.
+
+      #{colorize(:cyan, 'Examples')}
           Display a list of available plans
             bolt plan show
           Display documentation for the aggregate::count plan
@@ -525,33 +587,39 @@ module Bolt
     HELP
 
     PROJECT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           project
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt project <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Create and migrate Bolt projects
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt projects, run 'bolt guide project'.
+
+      #{colorize(:cyan, 'Actions')}
           init              Create a new Bolt project
           migrate           Migrate a Bolt project to the latest version
     HELP
 
     PROJECT_INIT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           init
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt project init [name] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Create a new Bolt project in the current working directory.
 
           Specify a name for the Bolt project. Defaults to the basename of the current working directory.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt projects, run 'bolt guide project'.
+
+      #{colorize(:cyan, 'Examples')}
           Create a new Bolt project using the directory as the project name.
             bolt project init
           Create a new Bolt project with a specified name.
@@ -561,139 +629,166 @@ module Bolt
     HELP
 
     PROJECT_MIGRATE_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           migrate
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt project migrate [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Migrate a Bolt project to use current best practices and the latest version of
           configuration files.
+
+      #{colorize(:cyan, 'Documentation')}
+          To learn more about Bolt projects, run 'bolt guide project'.
     HELP
 
     SCRIPT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           script
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt script <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a script on the specified targets.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about running scrips at https://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Actions')}
           run         Run a script on the specified targets.
     HELP
 
     SCRIPT_RUN_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           run
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt script run <script> [arguments] {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a script on the specified targets.
 
           Arguments passed to a script are passed literally and are not interpolated
           by the shell. Any arguments containing spaces or special characters should
           be quoted.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about running scrips at https://pup.pt/bolt-commands.
+
+      #{colorize(:cyan, 'Examples')}
           bolt script run myscript.sh 'echo hello' --targets target1,target2
     HELP
 
     SECRET_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           secret
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt secret <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Create encryption keys and encrypt and decrypt values.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about secrets plugins at http://pup.pt/bolt-plugins.
+
+      #{colorize(:cyan, 'Actions')}
           createkeys           Create new encryption keys
           encrypt              Encrypt a value
           decrypt              Decrypt a value
     HELP
 
     SECRET_CREATEKEYS_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           createkeys
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt secret createkeys [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Create new encryption keys.
+
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about secrets plugins at http://pup.pt/bolt-plugins.
     HELP
 
     SECRET_DECRYPT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           decrypt
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt secret decrypt <ciphertext> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Decrypt a value.
+
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about secrets plugins at http://pup.pt/bolt-plugins.
     HELP
 
     SECRET_ENCRYPT_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           encrypt
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
         bolt secret encrypt <plaintext> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Encrypt a value.
+
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about secrets plugins at http://pup.pt/bolt-plugins.
     HELP
 
     TASK_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           task
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt task <action> [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show and run Bolt tasks.
 
-      ACTIONS
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
+
+      #{colorize(:cyan, 'Actions')}
           run          Run a Bolt task
           show         Show available tasks and task documentation
     HELP
 
     TASK_RUN_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           run
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt task run <task name> [parameters] {--targets TARGETS | --query QUERY | --rerun FILTER}
             [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Run a task on the specified targets.
 
           Parameters take the form parameter=value.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
+
+      #{colorize(:cyan, 'Examples')}
           bolt task run package --targets target1,target2 action=status name=bash
     HELP
 
     TASK_SHOW_HELP = <<~HELP
-      NAME
+      #{colorize(:cyan, 'Name')}
           show
 
-      USAGE
+      #{colorize(:cyan, 'Usage')}
           bolt task show [task name] [options]
 
-      DESCRIPTION
+      #{colorize(:cyan, 'Description')}
           Show available tasks and task documentation.
 
           Omitting the name of a task will display a list of tasks available
@@ -702,7 +797,10 @@ module Bolt
           Providing the name of a task will display detailed documentation for
           the task, including a list of available parameters.
 
-      EXAMPLES
+      #{colorize(:cyan, 'Documentation')}
+          Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
+
+      #{colorize(:cyan, 'Examples')}
           Display a list of available tasks
             bolt task show
           Display documentation for the canary task
@@ -714,120 +812,108 @@ module Bolt
 
       @options = options
 
-      separator "\nINVENTORY OPTIONS"
-      define('-t', '--targets TARGETS',
-             'Identifies the targets of command.',
-             'Enter a comma-separated list of target URIs or group names.',
-             "Or read a target list from an input file '@<file>' or stdin '-'.",
-             'Example: --targets localhost,target_group,ssh://nix.com:23,winrm://windows.puppet.com',
-             'URI format is [protocol://]host[:port]',
-             "SSH is the default protocol; can be #{TRANSPORTS.keys.join(', ')}",
-             'For Windows targets, specify the winrm:// protocol if it has not be configured',
-             'For SSH, port defaults to `22`',
-             'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting',
+      separator "\n#{self.class.colorize(:cyan, 'Inventory options')}"
+      define('-t', '--targets TARGETS', 'Identifies the targets of the command.',
              "For more information, see 'bolt guide targets'.") do |targets|
         @options[:targets] ||= []
         @options[:targets] << Bolt::Util.get_arg_input(targets)
       end
-      define('-q', '--query QUERY', 'Query PuppetDB to determine the targets') do |query|
+      define('-q', '--query QUERY', 'Query PuppetDB to determine the targets.') do |query|
         @options[:query] = query
       end
-      define('--rerun FILTER', 'Retry on targets from the last run',
-             "'all' all targets that were part of the last run.",
-             "'failure' targets that failed in the last run.",
-             "'success' targets that succeeded in the last run.") do |rerun|
+      define("--rerun FILTER", "Retry on targets from the last run.",
+             "Available filters are 'all', 'failure', and 'success'.") do |rerun|
         @options[:rerun] = rerun
       end
-      define('--noop', 'See what changes Bolt will make without actually executing the changes') do |_|
+      define('--noop', 'See what changes Bolt will make without actually executing the changes.') do |_|
         @options[:noop] = true
       end
       define('--params PARAMETERS',
-             "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'") do |params|
+             "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'.") do |params|
         @options[:task_options] = parse_params(params)
       end
       define('-e', '--execute CODE',
-             "Puppet manifest code to apply to the targets") do |code|
+             "Puppet manifest code to apply to the targets.") do |code|
         @options[:code] = code
       end
-      define('--detail', 'Show resolved configuration for the targets') do |detail|
+      define('--detail', 'Show resolved configuration for the targets.') do |detail|
         @options[:detail] = detail
       end
 
-      separator "\nAUTHENTICATION OPTIONS"
-      define('-u', '--user USER', 'User to authenticate as') do |user|
+      separator "\n#{self.class.colorize(:cyan, 'Authentication options')}"
+      define('-u', '--user USER', 'User to authenticate as.') do |user|
         @options[:user] = user
       end
       define('-p', '--password PASSWORD',
-             'Password to authenticate with') do |password|
+             'Password to authenticate with.') do |password|
         @options[:password] = password
       end
-      define('--password-prompt', 'Prompt for user to input password') do |_password|
+      define('--password-prompt', 'Prompt for user to input password.') do |_password|
         $stderr.print "Please enter your password: "
         @options[:password] = $stdin.noecho(&:gets).chomp
         $stderr.puts
       end
-      define('--private-key KEY', 'Path to private ssh key to authenticate with') do |key|
+      define('--private-key KEY', 'Path to private ssh key to authenticate with.') do |key|
         @options[:'private-key'] = File.expand_path(key)
       end
-      define('--[no-]host-key-check', 'Check host keys with SSH') do |host_key_check|
+      define('--[no-]host-key-check', 'Check host keys with SSH.') do |host_key_check|
         @options[:'host-key-check'] = host_key_check
       end
-      define('--[no-]ssl', 'Use SSL with WinRM') do |ssl|
+      define('--[no-]ssl', 'Use SSL with WinRM.') do |ssl|
         @options[:ssl] = ssl
       end
-      define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM') do |ssl_verify|
+      define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM.') do |ssl_verify|
         @options[:'ssl-verify'] = ssl_verify
       end
 
-      separator "\nESCALATION OPTIONS"
-      define('--run-as USER', 'User to run as using privilege escalation') do |user|
+      separator "\n#{self.class.colorize(:cyan, 'Escalation options')}"
+      define('--run-as USER', 'User to run as using privilege escalation.') do |user|
         @options[:'run-as'] = user
       end
       define('--sudo-password PASSWORD',
-             'Password for privilege escalation') do |password|
+             'Password for privilege escalation.') do |password|
         @options[:'sudo-password'] = password
       end
-      define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password|
+      define('--sudo-password-prompt', 'Prompt for user to input escalation password.') do |_password|
         $stderr.print "Please enter your privilege escalation password: "
         @options[:'sudo-password'] = $stdin.noecho(&:gets).chomp
         $stderr.puts
       end
-      define('--sudo-executable EXEC', "Specify an executable for running as another user.",
-             "This option is experimental.") do |exec|
+      define('--sudo-executable EXEC', "Experimental. Specify an executable for running as another user.") do |exec|
         @options[:'sudo-executable'] = exec
       end
 
-      separator "\nRUN CONTEXT OPTIONS"
+      separator "\n#{self.class.colorize(:cyan, 'Run context options')}"
       define('-c', '--concurrency CONCURRENCY', Integer,
-             'Maximum number of simultaneous connections') do |concurrency|
+             'Maximum number of simultaneous connections.') do |concurrency|
         @options[:concurrency] = concurrency
       end
       define('--compile-concurrency CONCURRENCY', Integer,
-             'Maximum number of simultaneous manifest block compiles (default: number of cores)') do |concurrency|
+             'Maximum number of simultaneous manifest block compiles (default: number of cores).') do |concurrency|
         @options[:'compile-concurrency'] = concurrency
       end
       define('--[no-]cleanup',
-             'Whether to clean up temporary files created on targets') do |cleanup|
+             'Whether to clean up temporary files created on targets.') do |cleanup|
         @options[:cleanup] = cleanup
       end
       define('-m', '--modulepath MODULES',
              "List of directories containing modules, separated by '#{File::PATH_SEPARATOR}'",
-             'Directories are case-sensitive') do |modulepath|
+             'Directories are case-sensitive.') do |modulepath|
         # When specified from the CLI, modulepath entries are relative to pwd
         @options[:modulepath] = modulepath.split(File::PATH_SEPARATOR).map do |moduledir|
           File.expand_path(moduledir)
         end
       end
       define('--project PATH',
-             'Path to load the Bolt project from (default: autodiscovered from current dir)') do |path|
+             'Path to load the Bolt project from (default: autodiscovered from current dir).') do |path|
         @options[:project] = path
       end
       define('--hiera-config PATH',
-             'Specify where to load Hiera config from (default: ~/.puppetlabs/bolt/hiera.yaml)') do |path|
+             'Specify where to load Hiera config from (default: <project>/hiera.yaml).') do |path|
         @options[:'hiera-config'] = File.expand_path(path)
       end
       define('-i', '--inventoryfile PATH',
-             'Specify where to load inventory from (default: ~/.puppetlabs/bolt/inventory.yaml)') do |path|
+             'Specify where to load inventory from (default: <project>/inventory.yaml).') do |path|
         if ENV.include?(Bolt::Inventory::ENVIRONMENT_VAR)
           raise Bolt::CLIError, "Cannot pass inventory file when #{Bolt::Inventory::ENVIRONMENT_VAR} is set"
         end
@@ -837,8 +923,8 @@ module Bolt
         @options[:'save-rerun'] = save
       end
 
-      separator "\nREMOTE ENVIRONMENT OPTIONS"
-      define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target') do |envvar|
+      separator "\n#{self.class.colorize(:cyan, 'Remote environment options')}"
+      define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target.') do |envvar|
         unless envvar.include?('=')
           raise Bolt::CLIError, "Environment variables must be specified using 'myenvvar=key' format"
         end
@@ -846,47 +932,47 @@ module Bolt
         @options[:env_vars].store(*envvar.split('=', 2))
       end
 
-      separator "\nTRANSPORT OPTIONS"
+      separator "\n#{self.class.colorize(:cyan, 'Transport options')}"
       define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
-             "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
+             "Specify a default transport: #{TRANSPORTS.keys.join(', ')}.",
+             "For more information, see 'bolt guide transports'.") do |t|
         @options[:transport] = t
       end
-      define('--[no-]native-ssh', 'Whether to shell out to native SSH or use the net-ssh Ruby library.',
-             'This option is experimental') do |bool|
+      define('--[no-]native-ssh',
+             'Experimental. Whether to shell out to native SSH or use the net-ssh Ruby library.') do |bool|
         @options[:'native-ssh'] = bool
       end
-      define('--ssh-command EXEC', "Executable to use instead of the net-ssh Ruby library. ",
-             "This option is experimental.") do |exec|
+      define('--ssh-command EXEC', "Experimental. Executable to use instead of the net-ssh Ruby library.") do |exec|
         @options[:'ssh-command'] = exec
       end
-      define('--copy-command EXEC', "Command to copy files to remote hosts if using native SSH. ",
-             "This option is experimental.") do |exec|
+      define('--copy-command EXEC',
+             "Experimental. Command to copy files to remote hosts if using native SSH.") do |exec|
         @options[:'copy-command'] = exec
       end
-      define('--connect-timeout TIMEOUT', Integer, 'Connection timeout in seconds (defaults vary)') do |timeout|
+      define('--connect-timeout TIMEOUT', Integer, 'Connection timeout in seconds (defaults vary).') do |timeout|
         @options[:'connect-timeout'] = timeout
       end
-      define('--[no-]tty', 'Request a pseudo TTY on targets that support it') do |tty|
+      define('--[no-]tty', 'Request a pseudo TTY on targets that support it.') do |tty|
         @options[:tty] = tty
       end
-      define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target') do |tmpdir|
+      define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target.') do |tmpdir|
         @options[:tmpdir] = tmpdir
       end
 
-      separator "\nMODULE OPTIONS"
+      separator "\n#{self.class.colorize(:cyan, 'Module options')}"
       define('--[no-]resolve',
              'Use --no-resolve to install modules listed in the Puppetfile without resolving modules configured',
-             'in Bolt project configuration') do |resolve|
+             'in Bolt project configuration.') do |resolve|
         @options[:resolve] = resolve
       end
 
-      separator "\nPLAN OPTIONS"
+      separator "\n#{self.class.colorize(:cyan, 'Plan options')}"
       define('--pp', 'Create a new Puppet language plan.') do |_|
         @options[:puppet] = true
       end
 
-      separator "\nDISPLAY OPTIONS"
-      define('--filter FILTER', 'Filter tasks and plans by a matching substring') do |filter|
+      separator "\n#{self.class.colorize(:cyan, 'Display options')}"
+      define('--filter FILTER', 'Filter tasks and plans by a matching substring.') do |filter|
         unless /^[a-z0-9_:]+$/.match(filter)
           msg = "Illegal characters in filter string '#{filter}'. Filters must match a legal "\
                 "task or plan name."
@@ -894,13 +980,13 @@ module Bolt
         end
         @options[:filter] = filter
       end
-      define('--format FORMAT', 'Output format to use: human or json') do |format|
+      define('--format FORMAT', 'Output format to use: human, json, or rainbow.') do |format|
         @options[:format] = format
       end
-      define('--[no-]color', 'Whether to show output in color') do |color|
+      define('--[no-]color', 'Whether to show output in color.') do |color|
         @options[:color] = color
       end
-      define('-v', '--[no-]verbose', 'Display verbose logging') do |value|
+      define('-v', '--[no-]verbose', 'Display verbose logging.') do |value|
         @options[:verbose] = value
       end
       define('--stream',
@@ -909,25 +995,25 @@ module Bolt
              'a second time after the action is completed.') do |_|
         @options[:stream] = true
       end
-      define('--trace', 'Display error stack traces') do |_|
+      define('--trace', 'Display error stack traces.') do |_|
         @options[:trace] = true
       end
 
-      separator "\nADDITIONAL OPTIONS"
+      separator "\n#{self.class.colorize(:cyan, 'Additional options')}"
       define('--modules MODULES',
              'A comma-separated list of modules to install from the Puppet Forge',
              'when initializing a project. Resolves and installs all dependencies.') do |modules|
         @options[:modules] = modules.split(',').map { |mod| { 'name' => mod } }
       end
-      define('--force', 'Force a destructive action') do |_force|
+      define('--force', 'Force a destructive action.') do |_force|
         @options[:force] = true
       end
 
-      separator "\nGLOBAL OPTIONS"
-      define('-h', '--help', 'Display help') do |_|
+      separator "\n#{self.class.colorize(:cyan, 'Global options')}"
+      define('-h', '--help', 'Display help.') do |_|
         @options[:help] = true
       end
-      define('--version', 'Display the version') do |_|
+      define('--version', 'Display the version.') do |_|
         puts Bolt::VERSION
         raise Bolt::CLIExit
       end
@@ -937,10 +1023,10 @@ module Bolt
         @options[:log] = { 'console' => { 'level' => level } }
       end
       define('--clear-cache',
-             "Clear plugin cache before executing") do |_|
+             "Clear plugin cache before executing.") do |_|
         @options[:clear_cache] = true
       end
-      define('--plugin PLUGIN', 'Select the plugin to use') do |plug|
+      define('--plugin PLUGIN', 'Select the plugin to use.') do |plug|
         @options[:plugin] = plug
       end
     end