bolt 3.7.0 → 3.7.1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of bolt might be problematic. Click here for more details.

checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 575cccb1487a82a6537a83d5d23a89d9e3ed44898af25e2fe34acda2ecd765ae
4
- data.tar.gz: a9de53717fdcb5380f95ef5ee1fb26b3d28eaa59f92355d9558954d14192f307
3
+ metadata.gz: 741f798df2b4c7a46e45c5c87a41cd4e994506cdd202d26b6acafae7774135f8
4
+ data.tar.gz: 803789a5f6872e27656a733e94998acc9dde4d325d2d920b345a1c2848683f2f
5
5
  SHA512:
6
- metadata.gz: 60378d6872763f5fb557deae88207c29db0626d90562e37d80df1f604368629049da79ff0a0216602057566c7eb10892855f33a99b03bfc348fce8b443e7682d
7
- data.tar.gz: e2f8dd460e346648e53921e299db5b7beaf4ba1a0cd7efe95728e2e2d42c3e4b3624c40ef8a94a21b7e4be5003d67a1a64c48d1a36a9e314c4d7bb296ce85eab
6
+ metadata.gz: 85cb83b0a0bf02d1ba15b14ba5e5e75c6ff290e1acee71b0de06ea716f3698e91358aa6f9961757b088afa3c98d519ba10f79a6195c767492a87603759c2fc81
7
+ data.tar.gz: 8180f0827c3576e676e6fca59af7744d3e375023b44c0ebc2e691801a25f8fc1cac2487276661f7b40503e8ab1164ae07ee5f8343be9bb5be3088851e81eafaf
@@ -1,5 +1,31 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # An [apply action](applying_manifest_blocks.md#return-value-of-apply-action)
4
+ # returns an `ApplyResult`. An `ApplyResult` is part of a `ResultSet` object and
5
+ # contains information about the apply action.
6
+ #
7
+ # @param report
8
+ # The Puppet report from the apply action. Equivalent to calling `ApplyResult.value['report']`.
9
+ # The report is a hash representation of the [`Puppet::Transaction::Report`
10
+ # object](https://puppet.com/docs/puppet/latest/format_report.html), where each property
11
+ # corresponds to a key in the report hash. For more information, see [Result
12
+ # keys](applying_manifest_blocks.md#result-keys).
13
+ # @param target
14
+ # The target the result is from.
15
+ #
16
+ # @!method action
17
+ # The action performed. `ApplyResult.action` always returns the string `apply`.
18
+ # @!method error
19
+ # Returns an Error object constructed from the `_error` field of the result's value.
20
+ # @!method message
21
+ # The `_output` field of the result's value.
22
+ # @!method ok
23
+ # Whether the result was successful.
24
+ # @!method to_data
25
+ # A serialized representation of `ApplyResult`.
26
+ # @!method value
27
+ # A hash including the Puppet report from the apply action under a `report` key.
28
+ #
3
29
  Puppet::DataTypes.create_type('ApplyResult') do
4
30
  interface <<-PUPPET
5
31
  attributes => {
@@ -1,5 +1,32 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # The [run_container](plan_functions.md#run_container) plan function returns a
4
+ # `ContainerResult` object. A `ContainerResult` is a standalone object (not part
5
+ # of a `ResultSet`) that includes either the `stdout` and `stderr` values from
6
+ # running the container, or an `_error` object if the container exited with a
7
+ # nonzero exit code.
8
+ #
9
+ # @param value
10
+ # A hash including the `stdout`, `stderr`, and `exit_code` received from the
11
+ # container.
12
+ #
13
+ # @!method []
14
+ # Accesses the value hash directly and returns the value for the key. This
15
+ # function does not use dot notation. Call the function directly on the
16
+ # `ContainerResult`. For example, `$result[key]`.
17
+ # @!method error
18
+ # An object constructed from the `_error` field of the result's value.
19
+ # @!method ok
20
+ # Whether the result was successful.
21
+ # @!method status
22
+ # Either `success` if the result was successful or `failure`.
23
+ # @!method stdout
24
+ # The value of 'stdout' output by the container.
25
+ # @!method stderr
26
+ # The value of 'stderr' output by the container.
27
+ # @!method to_data
28
+ # A serialized representation of `ContainerResult`.
29
+ #
3
30
  Puppet::DataTypes.create_type('ContainerResult') do
4
31
  interface <<-PUPPET
5
32
  attributes => {
@@ -1,5 +1,48 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # `ResourceInstance` objects are used to store the observed and desired state of a
4
+ # target's resource and to track events for the resource. These objects do not
5
+ # modify or interact with a target's resources.
6
+ #
7
+ # > The `ResourceInstance` data type is experimental and might change in a future
8
+ # > release. You can learn more about this data type and how to use it in the
9
+ # > [experimental features
10
+ # > documentation](experimental_features.md#resourceinstance-data-type).
11
+ #
12
+ # @param events
13
+ # Events for the resource.
14
+ # @param desired_state
15
+ # [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
16
+ # the desired state of the resource.
17
+ # @param state
18
+ # [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
19
+ # the observed state of the resource.
20
+ # @param target
21
+ # The resource's target.
22
+ # @param title
23
+ # The [resource title](https://puppet.com/docs/puppet/latest/lang_resources.html#title).
24
+ # @param type
25
+ # The [resource type](https://puppet.com/docs/puppet/latest/lang_resources.html#resource-types).
26
+ #
27
+ # @!method []
28
+ # Accesses the `state` hash directly and returns the value for the specified
29
+ # attribute. This function does not use dot noation. Call the function directly
30
+ # on the `ResourceInstance`. For example, `$resource['ensure']`.
31
+ # @!method add_event(event)
32
+ # Add an event for the resource.
33
+ # @!method overwrite_desired_state(desired_state)
34
+ # Overwrites the desired state of the resource.
35
+ # @!method overwrite_state(state)
36
+ # Overwrites the observed state of the resource.
37
+ # @!method set_desired_state(desired_state)
38
+ # Sets attributes describing the desired state of the resource. Performs a shallow
39
+ # merge with existing desired state.
40
+ # @!method set_state(state)
41
+ # Sets attributes describing the observed state of the resource. Performs a shallow
42
+ # merge with existing state.
43
+ # @!method reference
44
+ # The resources reference string. For example, `File[/etc/puppetlabs]`.
45
+ #
3
46
  Puppet::DataTypes.create_type('ResourceInstance') do
4
47
  interface <<-PUPPET
5
48
  attributes => {
@@ -1,5 +1,34 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # For each target that you execute an action on, Bolt returns a `Result` object
4
+ # and adds the `Result` to a `ResultSet` object. A `Result` object contains
5
+ # information about the action you executed on the target.
6
+ #
7
+ # @param target
8
+ # The target the result is from.
9
+ # @param value
10
+ # The output or return of executing on the target.
11
+ #
12
+ # @!method []
13
+ # Accesses the `value` hash directly and returns the value for the key. This
14
+ # function does not use dot nation. Call the function directly on the `Result`.
15
+ # For example, `$result['key']`.
16
+ # @!method action
17
+ # The type of result. For example, `task` or `command`.
18
+ # @!method error
19
+ # An object constructed from the `_error` field of the result's `value`.
20
+ # @!method message
21
+ # The `_output` field of the result's value.
22
+ # @!method ok
23
+ # Whether the result was successful.
24
+ # @!method sensitive
25
+ # The `_sensitive` field of the result's value, wrapped in a `Sensitive` object.
26
+ # Call `unwrap()` to extract the value.
27
+ # @!method status
28
+ # Either `success` if the result was successful or `failure`.
29
+ # @!method to_data
30
+ # A serialized representation of `Result`.
31
+ #
3
32
  Puppet::DataTypes.create_type('Result') do
4
33
  interface <<-PUPPET
5
34
  attributes => {
@@ -1,5 +1,39 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # For each target that you execute an action on, Bolt returns a `Result` object
4
+ # and adds the `Result` to a `ResultSet` object. In the case of [apply
5
+ # actions](applying_manifest_blocks.md), Bolt returns a `ResultSet` with one or
6
+ # more `ApplyResult` objects.
7
+ #
8
+ # @param results
9
+ # All results in the set.
10
+ #
11
+ # @!method []
12
+ # The accessed results. This function does not use dot notation. Call the
13
+ # function directly on the `ResultSet`. For example, `$results[0]`.
14
+ # @!method count
15
+ # The number of results in the set.
16
+ # @!method empty
17
+ # Whether the set is empty.
18
+ # @!method error_set
19
+ # The set of failing results.
20
+ # @!method filter_set
21
+ # Filters a set of results by the contents of the block.
22
+ # @!method find(target_name)
23
+ # Retrieves a result for a specified target.
24
+ # @!method first
25
+ # The first result in the set. Useful for unwrapping single results.
26
+ # @!method names
27
+ # The names of all targets that have a `Result` in the set.
28
+ # @!method ok
29
+ # Whether all results were successful. Equivalent to `$results.error_set.empty`.
30
+ # @!method ok_set
31
+ # The set of successful results.
32
+ # @!method targets
33
+ # The list of targets that have results in the set.
34
+ # @!method to_data
35
+ # An array of serialized representations of each result in the set.
36
+ #
3
37
  Puppet::DataTypes.create_type('ResultSet') do
4
38
  interface <<-PUPPET
5
39
  attributes => {
@@ -1,5 +1,60 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # The `Target` object represents a target and its specific connection options.
4
+ #
5
+ # @param config
6
+ # The inventory configuration for the target. This function returns the
7
+ # configuration set directly on the target in `inventory.yaml` or set in
8
+ # a plan using `Target.new` or `set_config()`. It does not return default
9
+ # configuration values or configuration set in Bolt configuration files.
10
+ # @param facts
11
+ # The target's facts. This function does not look up facts for a target and
12
+ # only returns the facts specified in an `inventory.yaml` file or set on a
13
+ # target during a plan run. To retrieve facts for a target and set them in
14
+ # inventory, run the [facts](writing_plans.md#collect-facts-from-targets)
15
+ # plan or [puppetdb_fact](writing_plans.md#collect-facts-from-puppetdb)
16
+ # plan.
17
+ # @param features
18
+ # The target's features.
19
+ # @param name
20
+ # The target's human-readable name, or its URI if a name was not given.
21
+ # @param plugin_hooks
22
+ # The target's `plugin_hooks` [configuration
23
+ # options](bolt_inventory_reference.md#plugin-hooks-1).
24
+ # @param resources
25
+ # The target's resources. This function does not look up resources for a
26
+ # target and only returns resources set on a target during a plan run.
27
+ # @param safe_name
28
+ # The target's safe name. Equivalent to `name` if a name was given, or the
29
+ # target's `uri` with any password omitted.
30
+ # @param target_alias
31
+ # The target's aliases.
32
+ # @param uri
33
+ # The target's URI.
34
+ # @param vars
35
+ # The target's variables.
36
+ #
37
+ # @!method host
38
+ # The target's hostname.
39
+ # @!method password
40
+ # The password to use when connecting to the target.
41
+ # @!method port
42
+ # The target's connection port.
43
+ # @!method protocol
44
+ # The protocol used to connect to the target. This is equivalent to the target's
45
+ # `transport`, expect for targets using the `remote` transport. For example,
46
+ # a target with the URI `http://example.com` using the `remote` transport would
47
+ # return `http` for the `protocol`.
48
+ # @!method transport
49
+ # The transport used to connect to the target.
50
+ # @!method transport_config
51
+ # The merged configuration for the target's `transport`. This function returns
52
+ # configuration that includes defaults set by Bolt, configuration set in
53
+ # `inventory.yaml`, configuration set in `bolt-defaults.yaml`, and configuration
54
+ # set in a plan using `set_config()`.
55
+ # @!method user
56
+ # The user to connect to the target.
57
+ #
3
58
  Puppet::DataTypes.create_type('Target') do
4
59
  begin
5
60
  inventory = Puppet.lookup(:bolt_inventory)
@@ -8,6 +8,7 @@ require 'bolt/error'
8
8
  Puppet::Functions.create_function(:add_to_group) do
9
9
  # @param targets A pattern or array of patterns identifying a set of targets.
10
10
  # @param group The name of the group to add targets to.
11
+ # @return [Array[Target]] The targets.
11
12
  # @example Add new Target to group.
12
13
  # Target.new('foo@example.com', 'password' => 'secret').add_to_group('group1')
13
14
  # @example Add new target to group by name.
@@ -16,6 +16,7 @@ Puppet::Functions.create_function(:apply_prep) do
16
16
  # @param targets A pattern or array of patterns identifying a set of targets.
17
17
  # @param options Options hash.
18
18
  # @option options [Array] _required_modules An array of modules to sync to the target.
19
+ # @return [nil]
19
20
  # @example Prepare targets by name.
20
21
  # apply_prep('target1,target2')
21
22
  dispatch :apply_prep do
@@ -10,6 +10,7 @@ Puppet::Functions.create_function(:parallelize, Puppet::Functions::InternalFunct
10
10
  # Map a block onto an array, where each array element executes in parallel.
11
11
  # This function is experimental.
12
12
  # @param data The array to apply the block to.
13
+ # @param block The code block to execute for each array element.
13
14
  # @return [Array] An array of PlanResult objects. Each input from the input
14
15
  # array returns a corresponding PlanResult object.
15
16
  # @example Execute two tasks on two targets.
@@ -11,6 +11,7 @@ require 'bolt/error'
11
11
  Puppet::Functions.create_function(:remove_from_group) do
12
12
  # @param target A pattern identifying a single target.
13
13
  # @param group The name of the group to remove the target from.
14
+ # @return [nil]
14
15
  # @example Remove Target from group.
15
16
  # remove_from_group('foo@example.com', 'group1')
16
17
  # @example Remove failing Targets from the rest of a plan
@@ -9,6 +9,7 @@ Puppet::Functions.create_function(:write_file) do
9
9
  # @param content File content to write.
10
10
  # @param destination An absolute path on the target(s).
11
11
  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
12
+ # @param options A hash of additional options.
12
13
  # @option options [Boolean] _catch_errors Whether to catch raised errors.
13
14
  # @option options [String] _run_as User to run as using privilege escalation.
14
15
  # @return A list of results, one entry per target.
@@ -3,8 +3,10 @@
3
3
  # Repeat the block until it returns a truthy value. Returns the value.
4
4
  Puppet::Functions.create_function(:'ctrl::do_until') do
5
5
  # @param options A hash of additional options.
6
+ # @param block The code block to repeat.
6
7
  # @option options [Numeric] limit The number of times to repeat the block.
7
8
  # @option options [Numeric] interval The number of seconds to wait before repeating the block.
9
+ # @return [nil]
8
10
  # @example Run a task until it succeeds
9
11
  # ctrl::do_until() || {
10
12
  # run_task('test', $target, '_catch_errors' => true).ok()
data/guides/guide.txt ADDED
@@ -0,0 +1,17 @@
1
+ TOPIC
2
+ guide
3
+
4
+ DESCRIPTION
5
+ A guide is a person (or CLI tool ;D) who leads travelers through unknown or
6
+ unfamiliar locations. The term can also be applied to a person who leads others
7
+ to more abstract goals such as knowledge or wisdom.
8
+
9
+ Etymology: Originated sometime between 1325 and 1375. From Middle English
10
+ guide, from the Old French guide, from Old Occitan guida, from guidar, from
11
+ Frankish *wītan (“to show the way, lead”), from Proto-Germanic *wītaną (“to
12
+ see, know; go, depart”), from Proto-Indo-European *weyd- (“to see, know”).
13
+ Related also to English wit.
14
+
15
+ DOCUMENTATION
16
+ https://en.wikipedia.org/wiki/Guide
17
+ https://en.wiktionary.org/wiki/guide
data/guides/links.txt ADDED
@@ -0,0 +1,13 @@
1
+ TOPIC
2
+ links
3
+
4
+ DESCRIPTION
5
+ Bolt documentation https://bolt.guide
6
+ Ask a question in #bolt https://slack.puppet.com/
7
+ Contribute at https://github.com/puppetlabs/bolt/
8
+ Getting Started Guide https://pup.pt/bolt-getting-started
9
+ Reference Documentation https://pup.pt/bolt-reference
10
+ Troubleshooting Bolt https://pup.pt/bolt-troubleshooting
11
+ Bolt Developer Updates https://pup.pt/bolt-dev-updates
12
+ Bolt Changelog https://pup.pt/bolt-changelog
13
+ Bolt Examples https://pup.pt/bolt-examples
data/guides/targets.txt CHANGED
@@ -6,26 +6,24 @@ DESCRIPTION
6
6
  be physical, such as servers, or virtual, such as containers or virtual
7
7
  machines.
8
8
 
9
- Several of Bolt's commands connect to targets and run actions on them. When
10
- you run these commands, Bolt requires a list of targets to run the action
11
- on. For example, the `bolt script run` command and `Invoke-BoltScript`
12
- PowerShell cmdlet require you to provide a list of targets to run your
13
- script on. You can provide a list of targets to a command using one of the
14
- following command-line options:
9
+ Several of Bolt's commands connect to targets and run actions on them.
10
+ These commands require a target or targets to run on. You can specify
11
+ targets to a command using one of the following command-line options:
15
12
 
16
- Shell commands
17
- -t, --targets TARGETS
18
- -q, --query QUERY
19
- --rerun FILTER
13
+ *nix options Powershell options
14
+ -t, --targets TARGETS -T, -Targets TARGETS
15
+ -q, --query QUERY -Q, -Query QUERY
16
+ --rerun FILTER -Rerun FILTER
20
17
 
21
- PowerShell cmdlets
22
- -T, -Targets TARGETS
23
- -Q, -Query QUERY
24
- -Rerun FILTER
18
+ The 'targets' option accepts a comma-separated list of target URIs or group
19
+ names, or can read a target list from an input file '@<file>' or stdin '-'.
20
+ URIs can be specified with the format [protocol://][user@]host[:port]. To
21
+ learn more about available protocols and their defaults, run 'bolt guide
22
+ transports'.
25
23
 
26
24
  Typically, targets and their configuration and data are listed in a
27
25
  project's inventory file. For more information about inventory files,
28
26
  see 'bolt guide inventory'.
29
27
 
30
28
  DOCUMENTATION
31
- https://pup.pt/bolt-commands
29
+ https://pup.pt/bolt-commands
@@ -0,0 +1,23 @@
1
+ TOPIC
2
+ transports
3
+
4
+ DESCRIPTION
5
+ Bolt uses transports (also known as protocols) to establish a connection
6
+ with a target in order to run actions on the target. The default transport is
7
+ SSH, and you can see available transports along with their configuration
8
+ options and defaults at http://pup.pt/bolt-reference.
9
+
10
+ You can specify a transport for a target by prepending '<transport>://' to
11
+ the target's URI. For example, to connect to a target with hostname
12
+ 'example.com' as user 'Administrator' using the WinRM transport, you would
13
+ pass the following to the target flag:
14
+ winrm://Administrator@example.com
15
+
16
+ You can also specify a default transport for all targets by passing the
17
+ '--transport' flag on *nix systems and the '-Transport' flag in Powershell.
18
+ Finally, you can set the transport for a target in the inventory. For more
19
+ information about the Bolt inventory, run 'bolt guide inventory'.
20
+
21
+ DOCUMENTATION
22
+ https://pup.pt/bolt-commands#specify-a-transport
23
+ http://pup.pt/bolt-inventory#transport-configuration
@@ -156,18 +156,30 @@ module Bolt
156
156
  end
157
157
  end
158
158
 
159
+ COLORS = {
160
+ cyan: "36"
161
+ }.freeze
162
+
163
+ def self.colorize(color, string)
164
+ if $stdout.isatty
165
+ "\033[#{COLORS[color]}m#{string}\033[0m"
166
+ else
167
+ string
168
+ end
169
+ end
170
+
159
171
  BANNER = <<~HELP
160
- NAME
172
+ #{colorize(:cyan, 'Name')}
161
173
  bolt
162
174
 
163
- USAGE
175
+ #{colorize(:cyan, 'Usage')}
164
176
  bolt <subcommand> [action] [options]
165
177
 
166
- DESCRIPTION
178
+ #{colorize(:cyan, 'Description')}
167
179
  Bolt is an orchestration tool that automates the manual work it takes to
168
180
  maintain your infrastructure.
169
181
 
170
- SUBCOMMANDS
182
+ #{colorize(:cyan, 'Subcommands')}
171
183
  apply Apply Puppet manifest code
172
184
  command Run a command remotely
173
185
  file Copy files between the controller and targets
@@ -181,79 +193,92 @@ module Bolt
181
193
  secret Create encryption keys and encrypt and decrypt values
182
194
  task Show and run Bolt tasks
183
195
 
184
- GUIDES
196
+ #{colorize(:cyan, 'Guides')}
185
197
  For a list of guides on Bolt's concepts and features, run 'bolt guide'.
198
+ Find Bolt's documentation at https://bolt.guide.
186
199
  HELP
187
200
 
188
201
  APPLY_HELP = <<~HELP
189
- NAME
202
+ #{colorize(:cyan, 'Name')}
190
203
  apply
191
204
 
192
- USAGE
205
+ #{colorize(:cyan, 'Usage')}
193
206
  bolt apply [manifest] {--targets TARGETS | --query QUERY | --rerun FILTER}
194
207
  [options]
195
208
 
196
- DESCRIPTION
209
+ #{colorize(:cyan, 'Description')}
197
210
  Apply Puppet manifest code on the specified targets.
198
211
 
199
- EXAMPLES
212
+ #{colorize(:cyan, 'Documentation')}
213
+ For documentation see http://pup.pt/bolt-apply.
214
+
215
+ #{colorize(:cyan, 'Examples')}
200
216
  bolt apply manifest.pp -t target
201
217
  bolt apply -e "file { '/etc/puppetlabs': ensure => present }" -t target
202
218
  HELP
203
219
 
204
220
  COMMAND_HELP = <<~HELP
205
- NAME
221
+ #{colorize(:cyan, 'Name')}
206
222
  command
207
223
 
208
- USAGE
224
+ #{colorize(:cyan, 'Usage')}
209
225
  bolt command <action> [options]
210
226
 
211
- DESCRIPTION
227
+ #{colorize(:cyan, 'Description')}
212
228
  Run a command on the specified targets.
213
229
 
214
- ACTIONS
230
+ #{colorize(:cyan, 'Documentation')}
231
+ For documentation see http://pup.pt/bolt-commands.
232
+
233
+ #{colorize(:cyan, 'Actions')}
215
234
  run Run a command on the specified targets.
216
235
  HELP
217
236
 
218
237
  COMMAND_RUN_HELP = <<~HELP
219
- NAME
238
+ #{colorize(:cyan, 'Name')}
220
239
  run
221
240
 
222
- USAGE
241
+ #{colorize(:cyan, 'Usage')}
223
242
  bolt command run <command> {--targets TARGETS | --query QUERY | --rerun FILTER}
224
243
  [options]
225
244
 
226
- DESCRIPTION
245
+ #{colorize(:cyan, 'Description')}
227
246
  Run a command on the specified targets.
228
247
 
229
- EXAMPLES
248
+ #{colorize(:cyan, 'Documentation')}
249
+ For documentation see http://pup.pt/bolt-commands.
250
+
251
+ #{colorize(:cyan, 'Examples')}
230
252
  bolt command run 'uptime' -t target1,target2
231
253
  HELP
232
254
 
233
255
  FILE_HELP = <<~HELP
234
- NAME
256
+ #{colorize(:cyan, 'Name')}
235
257
  file
236
258
 
237
- USAGE
259
+ #{colorize(:cyan, 'Usage')}
238
260
  bolt file <action> [options]
239
261
 
240
- DESCRIPTION
241
- Copy files and directories between the controller and targets
262
+ #{colorize(:cyan, 'Description')}
263
+ Copy files and directories between the controller and targets.
264
+
265
+ #{colorize(:cyan, 'Documentation')}
266
+ For documentation see http://pup.pt/bolt-commands.
242
267
 
243
- ACTIONS
268
+ #{colorize(:cyan, 'Actions')}
244
269
  download Download a file or directory to the controller
245
270
  upload Upload a local file or directory from the controller
246
271
  HELP
247
272
 
248
273
  FILE_DOWNLOAD_HELP = <<~HELP
249
- NAME
274
+ #{colorize(:cyan, 'Name')}
250
275
  download
251
276
 
252
- USAGE
277
+ #{colorize(:cyan, 'Usage')}
253
278
  bolt file download <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
254
279
  [options]
255
280
 
256
- DESCRIPTION
281
+ #{colorize(:cyan, 'Description')}
257
282
  Download a file or directory from one or more targets.
258
283
 
259
284
  Downloaded files and directories are saved to the a subdirectory
@@ -261,64 +286,76 @@ module Bolt
261
286
  destination directory is expanded relative to the downloads
262
287
  subdirectory of the project directory.
263
288
 
264
- EXAMPLES
289
+ #{colorize(:cyan, 'Documentation')}
290
+ For documentation see http://pup.pt/bolt-commands.
291
+
292
+ #{colorize(:cyan, 'Examples')}
265
293
  bolt file download /etc/ssh_config ssh_config -t all
266
294
  HELP
267
295
 
268
296
  FILE_UPLOAD_HELP = <<~HELP
269
- NAME
297
+ #{colorize(:cyan, 'Name')}
270
298
  upload
271
299
 
272
- USAGE
300
+ #{colorize(:cyan, 'Usage')}
273
301
  bolt file upload <source> <destination> {--targets TARGETS | --query QUERY | --rerun FILTER}
274
302
  [options]
275
303
 
276
- DESCRIPTION
304
+ #{colorize(:cyan, 'Description')}
277
305
  Upload a local file or directory.
278
306
 
279
- EXAMPLES
307
+ #{colorize(:cyan, 'Documentation')}
308
+ For documentation see http://pup.pt/bolt-commands.
309
+
310
+ #{colorize(:cyan, 'Examples')}
280
311
  bolt file upload /tmp/source /etc/profile.d/login.sh -t target1
281
312
  HELP
282
313
 
283
314
  GROUP_HELP = <<~HELP
284
- NAME
315
+ #{colorize(:cyan, 'Name')}
285
316
  group
286
317
 
287
- USAGE
318
+ #{colorize(:cyan, 'Usage')}
288
319
  bolt group <action> [options]
289
320
 
290
- DESCRIPTION
321
+ #{colorize(:cyan, 'Description')}
291
322
  Show the list of groups in the inventory.
292
323
 
293
- ACTIONS
324
+ #{colorize(:cyan, 'Documentation')}
325
+ To learn more about the inventory run 'bolt guide inventory'.
326
+
327
+ #{colorize(:cyan, 'Actions')}
294
328
  show Show the list of groups in the inventory
295
329
  HELP
296
330
 
297
331
  GROUP_SHOW_HELP = <<~HELP
298
- NAME
332
+ #{colorize(:cyan, 'Name')}
299
333
  show
300
334
 
301
- USAGE
335
+ #{colorize(:cyan, 'Usage')}
302
336
  bolt group show [options]
303
337
 
304
- DESCRIPTION
338
+ #{colorize(:cyan, 'Description')}
305
339
  Show the list of groups in the inventory.
340
+
341
+ #{colorize(:cyan, 'Documentation')}
342
+ To learn more about the inventory run 'bolt guide inventory'.
306
343
  HELP
307
344
 
308
345
  GUIDE_HELP = <<~HELP
309
- NAME
346
+ #{colorize(:cyan, 'Name')}
310
347
  guide
311
348
 
312
- USAGE
349
+ #{colorize(:cyan, 'Usage')}
313
350
  bolt guide [topic] [options]
314
351
 
315
- DESCRIPTION
352
+ #{colorize(:cyan, 'Description')}
316
353
  View guides for Bolt's concepts and features.
317
354
 
318
355
  Omitting a topic will display a list of available guides,
319
356
  while providing a topic will display the relevant guide.
320
357
 
321
- EXAMPLES
358
+ #{colorize(:cyan, 'Examples')}
322
359
  View a list of available guides
323
360
  bolt guide
324
361
  View the 'project' guide page
@@ -326,49 +363,55 @@ module Bolt
326
363
  HELP
327
364
 
328
365
  INVENTORY_HELP = <<~HELP
329
- NAME
366
+ #{colorize(:cyan, 'Name')}
330
367
  inventory
331
368
 
332
- USAGE
369
+ #{colorize(:cyan, 'Usage')}
333
370
  bolt inventory <action> [options]
334
371
 
335
- DESCRIPTION
372
+ #{colorize(:cyan, 'Description')}
336
373
  Show the list of targets an action would run on.
337
374
 
338
- ACTIONS
375
+ #{colorize(:cyan, 'Documentation')}
376
+ To learn more about the inventory run 'bolt guide inventory'.
377
+
378
+ #{colorize(:cyan, 'Actions')}
339
379
  show Show the list of targets an action would run on
340
380
  HELP
341
381
 
342
382
  INVENTORY_SHOW_HELP = <<~HELP
343
- NAME
383
+ #{colorize(:cyan, 'Name')}
344
384
  show
345
385
 
346
- USAGE
386
+ #{colorize(:cyan, 'Usage')}
347
387
  bolt inventory show [options]
348
388
 
349
- DESCRIPTION
389
+ #{colorize(:cyan, 'Description')}
350
390
  Show the list of targets an action would run on. This command will list
351
391
  all targets in the project's inventory by default.
352
392
 
353
393
  To filter the targets in the list, use the --targets, --query, or --rerun
354
394
  options. To view detailed configuration and data for targets, use the
355
- --detail option.
395
+ --detail option. To learn more about the inventory run 'bolt guide inventory'.
396
+
397
+ #{colorize(:cyan, 'Documentation')}
398
+ To learn more about the inventory run 'bolt guide inventory'.
356
399
  HELP
357
400
 
358
401
  MODULE_HELP = <<~HELP
359
- NAME
402
+ #{colorize(:cyan, 'Name')}
360
403
  module
361
404
 
362
- USAGE
405
+ #{colorize(:cyan, 'Usage')}
363
406
  bolt module <action> [options]
364
407
 
365
- DESCRIPTION
366
- Manage Bolt project modules
408
+ #{colorize(:cyan, 'Description')}
409
+ Manage Bolt project modules.
367
410
 
368
- The module command is only supported when a project is configured
369
- with the 'modules' key.
411
+ #{colorize(:cyan, 'Documentation')}
412
+ To learn more about Bolt modules run 'bolt guide module'.
370
413
 
371
- ACTIONS
414
+ #{colorize(:cyan, 'Actions')}
372
415
  add Add a module to the project
373
416
  generate-types Generate type references to register in plans
374
417
  install Install the project's modules
@@ -376,77 +419,84 @@ module Bolt
376
419
  HELP
377
420
 
378
421
  MODULE_ADD_HELP = <<~HELP
379
- NAME
422
+ #{colorize(:cyan, 'Name')}
380
423
  add
381
424
 
382
- USAGE
425
+ #{colorize(:cyan, 'Usage')}
383
426
  bolt module add <module> [options]
384
427
 
385
- DESCRIPTION
428
+ #{colorize(:cyan, 'Description')}
386
429
  Add a module to the project.
387
430
 
388
431
  Module declarations are loaded from the project's configuration
389
432
  file. Bolt will automatically resolve all module dependencies,
390
433
  generate a Puppetfile, and install the modules.
391
434
 
392
- The module command is only supported when a project is configured
393
- with the 'modules' key.
435
+ #{colorize(:cyan, 'Documentation')}
436
+ To learn more about Bolt modules, run 'bolt guide module'.
394
437
  HELP
395
438
 
396
439
  MODULE_GENERATETYPES_HELP = <<~HELP
397
- NAME
440
+ #{colorize(:cyan, 'Name')}
398
441
  generate-types
399
442
 
400
- USAGE
443
+ #{colorize(:cyan, 'Usage')}
401
444
  bolt module generate-types [options]
402
445
 
403
- DESCRIPTION
404
- Generate type references to register in plans.
446
+ #{colorize(:cyan, 'Description')}
447
+ Generate type references to register in plans. To learn more about
448
+ Bolt modules, run 'bolt guide module'.
405
449
 
406
- The module command is only supported when a project is configured
407
- with the 'modules' key.
450
+ #{colorize(:cyan, 'Documentation')}
451
+ To learn more about Bolt modules, run 'bolt guide module'.
408
452
  HELP
409
453
 
410
454
  MODULE_INSTALL_HELP = <<~HELP
411
- NAME
455
+ #{colorize(:cyan, 'Name')}
412
456
  install
413
457
 
414
- USAGE
458
+ #{colorize(:cyan, 'Usage')}
415
459
  bolt module install [options]
416
460
 
417
- DESCRIPTION
461
+ #{colorize(:cyan, 'Description')}
418
462
  Install the project's modules.
419
463
 
420
464
  Module declarations are loaded from the project's configuration
421
465
  file. Bolt will automatically resolve all module dependencies,
422
466
  generate a Puppetfile, and install the modules.
467
+
468
+ #{colorize(:cyan, 'Documentation')}
469
+ To learn more about Bolt modules, run 'bolt guide module'.
423
470
  HELP
424
471
 
425
472
  MODULE_SHOW_HELP = <<~HELP
426
- NAME
473
+ #{colorize(:cyan, 'Name')}
427
474
  show
428
475
 
429
- USAGE
476
+ #{colorize(:cyan, 'Usage')}
430
477
  bolt module show [options]
431
478
 
432
- DESCRIPTION
479
+ #{colorize(:cyan, 'Description')}
433
480
  List modules available to the Bolt project.
434
481
 
435
- The module command is only supported when a project is configured
436
- with the 'modules' key.
482
+ #{colorize(:cyan, 'Documentation')}
483
+ To learn more about Bolt modules, run 'bolt guide module'.
437
484
  HELP
438
485
 
439
486
  PLAN_HELP = <<~HELP
440
- NAME
487
+ #{colorize(:cyan, 'Name')}
441
488
  plan
442
489
 
443
- USAGE
490
+ #{colorize(:cyan, 'Usage')}
444
491
  bolt plan <action> [options]
445
492
 
446
- DESCRIPTION
493
+ #{colorize(:cyan, 'Description')}
447
494
  Convert, create, show, and run Bolt plans.
448
495
 
449
- ACTIONS
496
+ #{colorize(:cyan, 'Documentation')}
497
+ Learn more about Bolt plans at https://pup.pt/bolt-plans.
498
+
499
+ #{colorize(:cyan, 'Actions')}
450
500
  convert Convert a YAML plan to a Bolt plan
451
501
  new Create a new plan in the current project
452
502
  run Run a plan on the specified targets
@@ -454,13 +504,13 @@ module Bolt
454
504
  HELP
455
505
 
456
506
  PLAN_CONVERT_HELP = <<~HELP
457
- NAME
507
+ #{colorize(:cyan, 'Name')}
458
508
  convert
459
509
 
460
- USAGE
510
+ #{colorize(:cyan, 'Usage')}
461
511
  bolt plan convert <plan name> [options]
462
512
 
463
- DESCRIPTION
513
+ #{colorize(:cyan, 'Description')}
464
514
  Convert a YAML plan to a Puppet language plan and print the converted
465
515
  plan to stdout.
466
516
 
@@ -468,47 +518,56 @@ module Bolt
468
518
  correct but has different behavior. Always verify a converted plan's
469
519
  functionality. Note that the converted plan is not written to a file.
470
520
 
471
- EXAMPLES
521
+ #{colorize(:cyan, 'Documentation')}
522
+ Learn more about Bolt plans at https://pup.pt/bolt-plans.
523
+
524
+ #{colorize(:cyan, 'Examples')}
472
525
  bolt plan convert myproject::myplan
473
526
  bolt plan convert path/to/plan/myplan.yaml
474
527
  HELP
475
528
 
476
529
  PLAN_NEW_HELP = <<~HELP
477
- NAME
530
+ #{colorize(:cyan, 'Name')}
478
531
  new
479
532
 
480
- USAGE
533
+ #{colorize(:cyan, 'Usage')}
481
534
  bolt plan new <plan name> [options]
482
535
 
483
- DESCRIPTION
536
+ #{colorize(:cyan, 'Description')}
484
537
  Create a new plan in the current project.
485
538
 
486
- EXAMPLES
539
+ #{colorize(:cyan, 'Documentation')}
540
+ Learn more about Bolt plans at https://pup.pt/bolt-plans.
541
+
542
+ #{colorize(:cyan, 'Examples')}
487
543
  bolt plan new myproject::myplan
488
544
  HELP
489
545
 
490
546
  PLAN_RUN_HELP = <<~HELP
491
- NAME
547
+ #{colorize(:cyan, 'Name')}
492
548
  run
493
549
 
494
- USAGE
550
+ #{colorize(:cyan, 'Usage')}
495
551
  bolt plan run <plan name> [parameters] [options]
496
552
 
497
- DESCRIPTION
553
+ #{colorize(:cyan, 'Description')}
498
554
  Run a plan on the specified targets.
499
555
 
500
- EXAMPLES
556
+ #{colorize(:cyan, 'Documentation')}
557
+ Learn more about Bolt plans at https://pup.pt/bolt-plans.
558
+
559
+ #{colorize(:cyan, 'Examples')}
501
560
  bolt plan run canary --targets target1,target2 command=hostname
502
561
  HELP
503
562
 
504
563
  PLAN_SHOW_HELP = <<~HELP
505
- NAME
564
+ #{colorize(:cyan, 'Name')}
506
565
  show
507
566
 
508
- USAGE
567
+ #{colorize(:cyan, 'Usage')}
509
568
  bolt plan show [plan name] [options]
510
569
 
511
- DESCRIPTION
570
+ #{colorize(:cyan, 'Description')}
512
571
  Show available plans and plan documentation.
513
572
 
514
573
  Omitting the name of a plan will display a list of plans available
@@ -517,7 +576,10 @@ module Bolt
517
576
  Providing the name of a plan will display detailed documentation for
518
577
  the plan, including a list of available parameters.
519
578
 
520
- EXAMPLES
579
+ #{colorize(:cyan, 'Documentation')}
580
+ Learn more about Bolt plans at https://pup.pt/bolt-plans.
581
+
582
+ #{colorize(:cyan, 'Examples')}
521
583
  Display a list of available plans
522
584
  bolt plan show
523
585
  Display documentation for the aggregate::count plan
@@ -525,33 +587,39 @@ module Bolt
525
587
  HELP
526
588
 
527
589
  PROJECT_HELP = <<~HELP
528
- NAME
590
+ #{colorize(:cyan, 'Name')}
529
591
  project
530
592
 
531
- USAGE
593
+ #{colorize(:cyan, 'Usage')}
532
594
  bolt project <action> [options]
533
595
 
534
- DESCRIPTION
596
+ #{colorize(:cyan, 'Description')}
535
597
  Create and migrate Bolt projects
536
598
 
537
- ACTIONS
599
+ #{colorize(:cyan, 'Documentation')}
600
+ To learn more about Bolt projects, run 'bolt guide project'.
601
+
602
+ #{colorize(:cyan, 'Actions')}
538
603
  init Create a new Bolt project
539
604
  migrate Migrate a Bolt project to the latest version
540
605
  HELP
541
606
 
542
607
  PROJECT_INIT_HELP = <<~HELP
543
- NAME
608
+ #{colorize(:cyan, 'Name')}
544
609
  init
545
610
 
546
- USAGE
611
+ #{colorize(:cyan, 'Usage')}
547
612
  bolt project init [name] [options]
548
613
 
549
- DESCRIPTION
614
+ #{colorize(:cyan, 'Description')}
550
615
  Create a new Bolt project in the current working directory.
551
616
 
552
617
  Specify a name for the Bolt project. Defaults to the basename of the current working directory.
553
618
 
554
- EXAMPLES
619
+ #{colorize(:cyan, 'Documentation')}
620
+ To learn more about Bolt projects, run 'bolt guide project'.
621
+
622
+ #{colorize(:cyan, 'Examples')}
555
623
  Create a new Bolt project using the directory as the project name.
556
624
  bolt project init
557
625
  Create a new Bolt project with a specified name.
@@ -561,139 +629,166 @@ module Bolt
561
629
  HELP
562
630
 
563
631
  PROJECT_MIGRATE_HELP = <<~HELP
564
- NAME
632
+ #{colorize(:cyan, 'Name')}
565
633
  migrate
566
634
 
567
- USAGE
635
+ #{colorize(:cyan, 'Usage')}
568
636
  bolt project migrate [options]
569
637
 
570
- DESCRIPTION
638
+ #{colorize(:cyan, 'Description')}
571
639
  Migrate a Bolt project to use current best practices and the latest version of
572
640
  configuration files.
641
+
642
+ #{colorize(:cyan, 'Documentation')}
643
+ To learn more about Bolt projects, run 'bolt guide project'.
573
644
  HELP
574
645
 
575
646
  SCRIPT_HELP = <<~HELP
576
- NAME
647
+ #{colorize(:cyan, 'Name')}
577
648
  script
578
649
 
579
- USAGE
650
+ #{colorize(:cyan, 'Usage')}
580
651
  bolt script <action> [options]
581
652
 
582
- DESCRIPTION
653
+ #{colorize(:cyan, 'Description')}
583
654
  Run a script on the specified targets.
584
655
 
585
- ACTIONS
656
+ #{colorize(:cyan, 'Documentation')}
657
+ Learn more about running scrips at https://pup.pt/bolt-commands.
658
+
659
+ #{colorize(:cyan, 'Actions')}
586
660
  run Run a script on the specified targets.
587
661
  HELP
588
662
 
589
663
  SCRIPT_RUN_HELP = <<~HELP
590
- NAME
664
+ #{colorize(:cyan, 'Name')}
591
665
  run
592
666
 
593
- USAGE
667
+ #{colorize(:cyan, 'Usage')}
594
668
  bolt script run <script> [arguments] {--targets TARGETS | --query QUERY | --rerun FILTER}
595
669
  [options]
596
670
 
597
- DESCRIPTION
671
+ #{colorize(:cyan, 'Description')}
598
672
  Run a script on the specified targets.
599
673
 
600
674
  Arguments passed to a script are passed literally and are not interpolated
601
675
  by the shell. Any arguments containing spaces or special characters should
602
676
  be quoted.
603
677
 
604
- EXAMPLES
678
+ #{colorize(:cyan, 'Documentation')}
679
+ Learn more about running scrips at https://pup.pt/bolt-commands.
680
+
681
+ #{colorize(:cyan, 'Examples')}
605
682
  bolt script run myscript.sh 'echo hello' --targets target1,target2
606
683
  HELP
607
684
 
608
685
  SECRET_HELP = <<~HELP
609
- NAME
686
+ #{colorize(:cyan, 'Name')}
610
687
  secret
611
688
 
612
- USAGE
689
+ #{colorize(:cyan, 'Usage')}
613
690
  bolt secret <action> [options]
614
691
 
615
- DESCRIPTION
692
+ #{colorize(:cyan, 'Description')}
616
693
  Create encryption keys and encrypt and decrypt values.
617
694
 
618
- ACTIONS
695
+ #{colorize(:cyan, 'Documentation')}
696
+ Learn more about secrets plugins at http://pup.pt/bolt-plugins.
697
+
698
+ #{colorize(:cyan, 'Actions')}
619
699
  createkeys Create new encryption keys
620
700
  encrypt Encrypt a value
621
701
  decrypt Decrypt a value
622
702
  HELP
623
703
 
624
704
  SECRET_CREATEKEYS_HELP = <<~HELP
625
- NAME
705
+ #{colorize(:cyan, 'Name')}
626
706
  createkeys
627
707
 
628
- USAGE
708
+ #{colorize(:cyan, 'Usage')}
629
709
  bolt secret createkeys [options]
630
710
 
631
- DESCRIPTION
711
+ #{colorize(:cyan, 'Description')}
632
712
  Create new encryption keys.
713
+
714
+ #{colorize(:cyan, 'Documentation')}
715
+ Learn more about secrets plugins at http://pup.pt/bolt-plugins.
633
716
  HELP
634
717
 
635
718
  SECRET_DECRYPT_HELP = <<~HELP
636
- NAME
719
+ #{colorize(:cyan, 'Name')}
637
720
  decrypt
638
721
 
639
- USAGE
722
+ #{colorize(:cyan, 'Usage')}
640
723
  bolt secret decrypt <ciphertext> [options]
641
724
 
642
- DESCRIPTION
725
+ #{colorize(:cyan, 'Description')}
643
726
  Decrypt a value.
727
+
728
+ #{colorize(:cyan, 'Documentation')}
729
+ Learn more about secrets plugins at http://pup.pt/bolt-plugins.
644
730
  HELP
645
731
 
646
732
  SECRET_ENCRYPT_HELP = <<~HELP
647
- NAME
733
+ #{colorize(:cyan, 'Name')}
648
734
  encrypt
649
735
 
650
- USAGE
736
+ #{colorize(:cyan, 'Usage')}
651
737
  bolt secret encrypt <plaintext> [options]
652
738
 
653
- DESCRIPTION
739
+ #{colorize(:cyan, 'Description')}
654
740
  Encrypt a value.
741
+
742
+ #{colorize(:cyan, 'Documentation')}
743
+ Learn more about secrets plugins at http://pup.pt/bolt-plugins.
655
744
  HELP
656
745
 
657
746
  TASK_HELP = <<~HELP
658
- NAME
747
+ #{colorize(:cyan, 'Name')}
659
748
  task
660
749
 
661
- USAGE
750
+ #{colorize(:cyan, 'Usage')}
662
751
  bolt task <action> [options]
663
752
 
664
- DESCRIPTION
753
+ #{colorize(:cyan, 'Description')}
665
754
  Show and run Bolt tasks.
666
755
 
667
- ACTIONS
756
+ #{colorize(:cyan, 'Documentation')}
757
+ Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
758
+
759
+ #{colorize(:cyan, 'Actions')}
668
760
  run Run a Bolt task
669
761
  show Show available tasks and task documentation
670
762
  HELP
671
763
 
672
764
  TASK_RUN_HELP = <<~HELP
673
- NAME
765
+ #{colorize(:cyan, 'Name')}
674
766
  run
675
767
 
676
- USAGE
768
+ #{colorize(:cyan, 'Usage')}
677
769
  bolt task run <task name> [parameters] {--targets TARGETS | --query QUERY | --rerun FILTER}
678
770
  [options]
679
771
 
680
- DESCRIPTION
772
+ #{colorize(:cyan, 'Description')}
681
773
  Run a task on the specified targets.
682
774
 
683
775
  Parameters take the form parameter=value.
684
776
 
685
- EXAMPLES
777
+ #{colorize(:cyan, 'Documentation')}
778
+ Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
779
+
780
+ #{colorize(:cyan, 'Examples')}
686
781
  bolt task run package --targets target1,target2 action=status name=bash
687
782
  HELP
688
783
 
689
784
  TASK_SHOW_HELP = <<~HELP
690
- NAME
785
+ #{colorize(:cyan, 'Name')}
691
786
  show
692
787
 
693
- USAGE
788
+ #{colorize(:cyan, 'Usage')}
694
789
  bolt task show [task name] [options]
695
790
 
696
- DESCRIPTION
791
+ #{colorize(:cyan, 'Description')}
697
792
  Show available tasks and task documentation.
698
793
 
699
794
  Omitting the name of a task will display a list of tasks available
@@ -702,7 +797,10 @@ module Bolt
702
797
  Providing the name of a task will display detailed documentation for
703
798
  the task, including a list of available parameters.
704
799
 
705
- EXAMPLES
800
+ #{colorize(:cyan, 'Documentation')}
801
+ Learn more about Bolt tasks at http://pup.pt/bolt-tasks.
802
+
803
+ #{colorize(:cyan, 'Examples')}
706
804
  Display a list of available tasks
707
805
  bolt task show
708
806
  Display documentation for the canary task
@@ -714,120 +812,108 @@ module Bolt
714
812
 
715
813
  @options = options
716
814
 
717
- separator "\nINVENTORY OPTIONS"
718
- define('-t', '--targets TARGETS',
719
- 'Identifies the targets of command.',
720
- 'Enter a comma-separated list of target URIs or group names.',
721
- "Or read a target list from an input file '@<file>' or stdin '-'.",
722
- 'Example: --targets localhost,target_group,ssh://nix.com:23,winrm://windows.puppet.com',
723
- 'URI format is [protocol://]host[:port]',
724
- "SSH is the default protocol; can be #{TRANSPORTS.keys.join(', ')}",
725
- 'For Windows targets, specify the winrm:// protocol if it has not be configured',
726
- 'For SSH, port defaults to `22`',
727
- 'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting',
815
+ separator "\n#{self.class.colorize(:cyan, 'Inventory options')}"
816
+ define('-t', '--targets TARGETS', 'Identifies the targets of the command.',
728
817
  "For more information, see 'bolt guide targets'.") do |targets|
729
818
  @options[:targets] ||= []
730
819
  @options[:targets] << Bolt::Util.get_arg_input(targets)
731
820
  end
732
- define('-q', '--query QUERY', 'Query PuppetDB to determine the targets') do |query|
821
+ define('-q', '--query QUERY', 'Query PuppetDB to determine the targets.') do |query|
733
822
  @options[:query] = query
734
823
  end
735
- define('--rerun FILTER', 'Retry on targets from the last run',
736
- "'all' all targets that were part of the last run.",
737
- "'failure' targets that failed in the last run.",
738
- "'success' targets that succeeded in the last run.") do |rerun|
824
+ define("--rerun FILTER", "Retry on targets from the last run.",
825
+ "Available filters are 'all', 'failure', and 'success'.") do |rerun|
739
826
  @options[:rerun] = rerun
740
827
  end
741
- define('--noop', 'See what changes Bolt will make without actually executing the changes') do |_|
828
+ define('--noop', 'See what changes Bolt will make without actually executing the changes.') do |_|
742
829
  @options[:noop] = true
743
830
  end
744
831
  define('--params PARAMETERS',
745
- "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'") do |params|
832
+ "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'.") do |params|
746
833
  @options[:task_options] = parse_params(params)
747
834
  end
748
835
  define('-e', '--execute CODE',
749
- "Puppet manifest code to apply to the targets") do |code|
836
+ "Puppet manifest code to apply to the targets.") do |code|
750
837
  @options[:code] = code
751
838
  end
752
- define('--detail', 'Show resolved configuration for the targets') do |detail|
839
+ define('--detail', 'Show resolved configuration for the targets.') do |detail|
753
840
  @options[:detail] = detail
754
841
  end
755
842
 
756
- separator "\nAUTHENTICATION OPTIONS"
757
- define('-u', '--user USER', 'User to authenticate as') do |user|
843
+ separator "\n#{self.class.colorize(:cyan, 'Authentication options')}"
844
+ define('-u', '--user USER', 'User to authenticate as.') do |user|
758
845
  @options[:user] = user
759
846
  end
760
847
  define('-p', '--password PASSWORD',
761
- 'Password to authenticate with') do |password|
848
+ 'Password to authenticate with.') do |password|
762
849
  @options[:password] = password
763
850
  end
764
- define('--password-prompt', 'Prompt for user to input password') do |_password|
851
+ define('--password-prompt', 'Prompt for user to input password.') do |_password|
765
852
  $stderr.print "Please enter your password: "
766
853
  @options[:password] = $stdin.noecho(&:gets).chomp
767
854
  $stderr.puts
768
855
  end
769
- define('--private-key KEY', 'Path to private ssh key to authenticate with') do |key|
856
+ define('--private-key KEY', 'Path to private ssh key to authenticate with.') do |key|
770
857
  @options[:'private-key'] = File.expand_path(key)
771
858
  end
772
- define('--[no-]host-key-check', 'Check host keys with SSH') do |host_key_check|
859
+ define('--[no-]host-key-check', 'Check host keys with SSH.') do |host_key_check|
773
860
  @options[:'host-key-check'] = host_key_check
774
861
  end
775
- define('--[no-]ssl', 'Use SSL with WinRM') do |ssl|
862
+ define('--[no-]ssl', 'Use SSL with WinRM.') do |ssl|
776
863
  @options[:ssl] = ssl
777
864
  end
778
- define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM') do |ssl_verify|
865
+ define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM.') do |ssl_verify|
779
866
  @options[:'ssl-verify'] = ssl_verify
780
867
  end
781
868
 
782
- separator "\nESCALATION OPTIONS"
783
- define('--run-as USER', 'User to run as using privilege escalation') do |user|
869
+ separator "\n#{self.class.colorize(:cyan, 'Escalation options')}"
870
+ define('--run-as USER', 'User to run as using privilege escalation.') do |user|
784
871
  @options[:'run-as'] = user
785
872
  end
786
873
  define('--sudo-password PASSWORD',
787
- 'Password for privilege escalation') do |password|
874
+ 'Password for privilege escalation.') do |password|
788
875
  @options[:'sudo-password'] = password
789
876
  end
790
- define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password|
877
+ define('--sudo-password-prompt', 'Prompt for user to input escalation password.') do |_password|
791
878
  $stderr.print "Please enter your privilege escalation password: "
792
879
  @options[:'sudo-password'] = $stdin.noecho(&:gets).chomp
793
880
  $stderr.puts
794
881
  end
795
- define('--sudo-executable EXEC', "Specify an executable for running as another user.",
796
- "This option is experimental.") do |exec|
882
+ define('--sudo-executable EXEC', "Experimental. Specify an executable for running as another user.") do |exec|
797
883
  @options[:'sudo-executable'] = exec
798
884
  end
799
885
 
800
- separator "\nRUN CONTEXT OPTIONS"
886
+ separator "\n#{self.class.colorize(:cyan, 'Run context options')}"
801
887
  define('-c', '--concurrency CONCURRENCY', Integer,
802
- 'Maximum number of simultaneous connections') do |concurrency|
888
+ 'Maximum number of simultaneous connections.') do |concurrency|
803
889
  @options[:concurrency] = concurrency
804
890
  end
805
891
  define('--compile-concurrency CONCURRENCY', Integer,
806
- 'Maximum number of simultaneous manifest block compiles (default: number of cores)') do |concurrency|
892
+ 'Maximum number of simultaneous manifest block compiles (default: number of cores).') do |concurrency|
807
893
  @options[:'compile-concurrency'] = concurrency
808
894
  end
809
895
  define('--[no-]cleanup',
810
- 'Whether to clean up temporary files created on targets') do |cleanup|
896
+ 'Whether to clean up temporary files created on targets.') do |cleanup|
811
897
  @options[:cleanup] = cleanup
812
898
  end
813
899
  define('-m', '--modulepath MODULES',
814
900
  "List of directories containing modules, separated by '#{File::PATH_SEPARATOR}'",
815
- 'Directories are case-sensitive') do |modulepath|
901
+ 'Directories are case-sensitive.') do |modulepath|
816
902
  # When specified from the CLI, modulepath entries are relative to pwd
817
903
  @options[:modulepath] = modulepath.split(File::PATH_SEPARATOR).map do |moduledir|
818
904
  File.expand_path(moduledir)
819
905
  end
820
906
  end
821
907
  define('--project PATH',
822
- 'Path to load the Bolt project from (default: autodiscovered from current dir)') do |path|
908
+ 'Path to load the Bolt project from (default: autodiscovered from current dir).') do |path|
823
909
  @options[:project] = path
824
910
  end
825
911
  define('--hiera-config PATH',
826
- 'Specify where to load Hiera config from (default: ~/.puppetlabs/bolt/hiera.yaml)') do |path|
912
+ 'Specify where to load Hiera config from (default: <project>/hiera.yaml).') do |path|
827
913
  @options[:'hiera-config'] = File.expand_path(path)
828
914
  end
829
915
  define('-i', '--inventoryfile PATH',
830
- 'Specify where to load inventory from (default: ~/.puppetlabs/bolt/inventory.yaml)') do |path|
916
+ 'Specify where to load inventory from (default: <project>/inventory.yaml).') do |path|
831
917
  if ENV.include?(Bolt::Inventory::ENVIRONMENT_VAR)
832
918
  raise Bolt::CLIError, "Cannot pass inventory file when #{Bolt::Inventory::ENVIRONMENT_VAR} is set"
833
919
  end
@@ -837,8 +923,8 @@ module Bolt
837
923
  @options[:'save-rerun'] = save
838
924
  end
839
925
 
840
- separator "\nREMOTE ENVIRONMENT OPTIONS"
841
- define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target') do |envvar|
926
+ separator "\n#{self.class.colorize(:cyan, 'Remote environment options')}"
927
+ define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target.') do |envvar|
842
928
  unless envvar.include?('=')
843
929
  raise Bolt::CLIError, "Environment variables must be specified using 'myenvvar=key' format"
844
930
  end
@@ -846,47 +932,47 @@ module Bolt
846
932
  @options[:env_vars].store(*envvar.split('=', 2))
847
933
  end
848
934
 
849
- separator "\nTRANSPORT OPTIONS"
935
+ separator "\n#{self.class.colorize(:cyan, 'Transport options')}"
850
936
  define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
851
- "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
937
+ "Specify a default transport: #{TRANSPORTS.keys.join(', ')}.",
938
+ "For more information, see 'bolt guide transports'.") do |t|
852
939
  @options[:transport] = t
853
940
  end
854
- define('--[no-]native-ssh', 'Whether to shell out to native SSH or use the net-ssh Ruby library.',
855
- 'This option is experimental') do |bool|
941
+ define('--[no-]native-ssh',
942
+ 'Experimental. Whether to shell out to native SSH or use the net-ssh Ruby library.') do |bool|
856
943
  @options[:'native-ssh'] = bool
857
944
  end
858
- define('--ssh-command EXEC', "Executable to use instead of the net-ssh Ruby library. ",
859
- "This option is experimental.") do |exec|
945
+ define('--ssh-command EXEC', "Experimental. Executable to use instead of the net-ssh Ruby library.") do |exec|
860
946
  @options[:'ssh-command'] = exec
861
947
  end
862
- define('--copy-command EXEC', "Command to copy files to remote hosts if using native SSH. ",
863
- "This option is experimental.") do |exec|
948
+ define('--copy-command EXEC',
949
+ "Experimental. Command to copy files to remote hosts if using native SSH.") do |exec|
864
950
  @options[:'copy-command'] = exec
865
951
  end
866
- define('--connect-timeout TIMEOUT', Integer, 'Connection timeout in seconds (defaults vary)') do |timeout|
952
+ define('--connect-timeout TIMEOUT', Integer, 'Connection timeout in seconds (defaults vary).') do |timeout|
867
953
  @options[:'connect-timeout'] = timeout
868
954
  end
869
- define('--[no-]tty', 'Request a pseudo TTY on targets that support it') do |tty|
955
+ define('--[no-]tty', 'Request a pseudo TTY on targets that support it.') do |tty|
870
956
  @options[:tty] = tty
871
957
  end
872
- define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target') do |tmpdir|
958
+ define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target.') do |tmpdir|
873
959
  @options[:tmpdir] = tmpdir
874
960
  end
875
961
 
876
- separator "\nMODULE OPTIONS"
962
+ separator "\n#{self.class.colorize(:cyan, 'Module options')}"
877
963
  define('--[no-]resolve',
878
964
  'Use --no-resolve to install modules listed in the Puppetfile without resolving modules configured',
879
- 'in Bolt project configuration') do |resolve|
965
+ 'in Bolt project configuration.') do |resolve|
880
966
  @options[:resolve] = resolve
881
967
  end
882
968
 
883
- separator "\nPLAN OPTIONS"
969
+ separator "\n#{self.class.colorize(:cyan, 'Plan options')}"
884
970
  define('--pp', 'Create a new Puppet language plan.') do |_|
885
971
  @options[:puppet] = true
886
972
  end
887
973
 
888
- separator "\nDISPLAY OPTIONS"
889
- define('--filter FILTER', 'Filter tasks and plans by a matching substring') do |filter|
974
+ separator "\n#{self.class.colorize(:cyan, 'Display options')}"
975
+ define('--filter FILTER', 'Filter tasks and plans by a matching substring.') do |filter|
890
976
  unless /^[a-z0-9_:]+$/.match(filter)
891
977
  msg = "Illegal characters in filter string '#{filter}'. Filters must match a legal "\
892
978
  "task or plan name."
@@ -894,13 +980,13 @@ module Bolt
894
980
  end
895
981
  @options[:filter] = filter
896
982
  end
897
- define('--format FORMAT', 'Output format to use: human or json') do |format|
983
+ define('--format FORMAT', 'Output format to use: human, json, or rainbow.') do |format|
898
984
  @options[:format] = format
899
985
  end
900
- define('--[no-]color', 'Whether to show output in color') do |color|
986
+ define('--[no-]color', 'Whether to show output in color.') do |color|
901
987
  @options[:color] = color
902
988
  end
903
- define('-v', '--[no-]verbose', 'Display verbose logging') do |value|
989
+ define('-v', '--[no-]verbose', 'Display verbose logging.') do |value|
904
990
  @options[:verbose] = value
905
991
  end
906
992
  define('--stream',
@@ -909,25 +995,25 @@ module Bolt
909
995
  'a second time after the action is completed.') do |_|
910
996
  @options[:stream] = true
911
997
  end
912
- define('--trace', 'Display error stack traces') do |_|
998
+ define('--trace', 'Display error stack traces.') do |_|
913
999
  @options[:trace] = true
914
1000
  end
915
1001
 
916
- separator "\nADDITIONAL OPTIONS"
1002
+ separator "\n#{self.class.colorize(:cyan, 'Additional options')}"
917
1003
  define('--modules MODULES',
918
1004
  'A comma-separated list of modules to install from the Puppet Forge',
919
1005
  'when initializing a project. Resolves and installs all dependencies.') do |modules|
920
1006
  @options[:modules] = modules.split(',').map { |mod| { 'name' => mod } }
921
1007
  end
922
- define('--force', 'Force a destructive action') do |_force|
1008
+ define('--force', 'Force a destructive action.') do |_force|
923
1009
  @options[:force] = true
924
1010
  end
925
1011
 
926
- separator "\nGLOBAL OPTIONS"
927
- define('-h', '--help', 'Display help') do |_|
1012
+ separator "\n#{self.class.colorize(:cyan, 'Global options')}"
1013
+ define('-h', '--help', 'Display help.') do |_|
928
1014
  @options[:help] = true
929
1015
  end
930
- define('--version', 'Display the version') do |_|
1016
+ define('--version', 'Display the version.') do |_|
931
1017
  puts Bolt::VERSION
932
1018
  raise Bolt::CLIExit
933
1019
  end
@@ -937,10 +1023,10 @@ module Bolt
937
1023
  @options[:log] = { 'console' => { 'level' => level } }
938
1024
  end
939
1025
  define('--clear-cache',
940
- "Clear plugin cache before executing") do |_|
1026
+ "Clear plugin cache before executing.") do |_|
941
1027
  @options[:clear_cache] = true
942
1028
  end
943
- define('--plugin PLUGIN', 'Select the plugin to use') do |plug|
1029
+ define('--plugin PLUGIN', 'Select the plugin to use.') do |plug|
944
1030
  @options[:plugin] = plug
945
1031
  end
946
1032
  end