Bolt - 3.27.1


New features

  • Support for running bolt with net-ssh 7.x

Bolt now supports running with net-ssh 7. The 7 series of net-ssh contains
breaking changes (removal of some supported algoriths for example) and
bolt 3 packages will continue to ship with the 6 series.

  • Add transport for FreeBSD jails (#3160)

FreeBSD has support for jails since FreeBSD 4.0 (released in 2000).

Add a new 'jail' transport to Bolt to allow management of jails on
FreeBSD. This feature is currently considered experimental.

Contributed by Romain Tartière

Bolt 2.27.0

This version of Bolt was not released.

Bolt 3.26.2 (2022-11-16)

New features

  • Support for new platforms

Bolt packages are now available for Fedora 36 and Ubuntu 22.04.


  • Removed support for Fedora 34, Debian 9

Bolt 3.26.1 (2022-08-15)

New features

  • Support globbing group names

Bolt now supports selecting group names with glob patterns when
selecting targets.

Bug fixes

  • Improve performance when using the 'puppetdb' plugin with many nodes

Using the 'puppetdb' plugin with many thousands of nodes resulted in
degenerate performance, sometimes taking minutes to resolve simple
queries. This is now resolved and these queries should execute

  • Properly print hiera data with bolt lookup

The human outputter can now properly print hiera data including
values that are hashes.

Bolt 3.25.0 (2022-07-27)

New features

  • Include catalog in ApplyResult objects

The ApplyResult object now includes a catalog attribute that
includes the catalog used during an apply. The catalog is masked using
the Sensitive data type to prevent sensitive information in the
catalog from being printed to the console or Bolt logs.

  • Allow larger set of characters in group and alias names

Group and alias names can now include any character other than
whitespace characters and commas.

  • Support installing any git-based module

Bolt now supports installing any git-based module. Previously, Bolt
only supported installing and resolving dependencies for modules
hosted in a public GitHub repository. Now, Bolt will check both GitHub
and GitLab before falling back to cloning a module's metadata using
the git executable. This allows users to install modules from
private repositories, or from locations other than GitHub.

  • Add bash_task_helper to bundled modules

Bolt now ships with the bolt_task_helper module which includes a
library for helping write Bash tasks.

  • Update bundled modules to latest version

The following bundled modules have been updated to their latest versions:

Bug fixes

  • Restrict whitespace characters and commas in target names

Bolt now raises a validation error when a target name includes a
whitespace character or comma. Previously, these characters were
allowed, but Bolt would not be able to retrieve the target from the
inventory by name.

  • Configure proxy when retrieving metadata for git-based modules

Bolt now configures a proxy when module-install.proxy is set and it
retrieves metadata for git-based modules. Previously, Bolt was only
configuring a proxy when it resolved and installed modules.

Bolt 3.24.0 (2022-06-29)

New features

  • Support extended globs for target matching from CLI

Bolt now supports extended globs for target matching in CLI
--targets option.

Contributed by Yury Bushmelev

  • Support interpreters in LXD transport configuration

Bolt now also supports setting the interpreters configuration option
for the LXD transport.

Contributed by jonasdemoor

  • Update puppetlabs-reboot to 4.2.0

The bundled module puppetlabs-reboot has been updated to version

Bug fixes

  • Execute commands over winrm in separate shell instances

Bolt now opens a new shell instance each time it runs a command over
winrm. Previously, Bolt used a single shell instance to run all
commands, preventing Bolt from properly cleaning up temporary files in
some instances.

  • Correctly print secret key paths when using rainbow format

Bolt no longer errors when running bolt secret createkeys --format rainbow or New-BoltSecretKey -Format rainbow.

  • Don't store sensitive parameter values when running plans over PCP

Bolt no longer submits sensitive parameter values to the PE
Orchestrator service when running plans over the PCP transport.


  • Remove support for Fedora 32, Ubuntu 16.04

Bolt 3.23.1 (2022-06-15)

Bug fixes

  • Support extensions in local transport on Windows controllers

The local transport now supports the extensions config option when
running Bolt on a Windows controller.

  • Collect fact values from a named PuppetDB instance using puppetdb


The puppetdb plugin now correctly connects to a named PuppetDB
instance when collecting fact values. Previously, the plugin only
connected to the named PuppetDB instance when querying certnames.

Bolt 3.23.0 (2022-06-06)

New features

  • RedHat 9 packages

Bolt now ships packages for RedHat 9.

  • SLES 15 packages

Bolt now ships packages for SLES 15.

  • macOS 12 packages

Bolt now ships packages for macOS 12.

  • Bolt can now be run with Ruby 3

The bolt gem can now be run with Ruby 3.

Contributed by Lucy Wyman

  • Connect to multiple PuppetDB instances

Bolt now supports connecting to multiple PuppetDB instances. For more
information, see Connecting Bolt to

The following bundled modules have been updated to their latest versions:

Bug fixes

  • Include a plan's docstring in plan show output

The bolt plan show <PLAN> and Get-BoltPlan -Name <PLAN> commands
now include a plan's docstring in the output, even when the plan
includes a @summary tag. Previously, Bolt would only display a
plan's summary or docstring, but not both.

  • Support running tasks in no-op mode over pcp

Bolt no longer errors when running tasks in no-op mode over the pcp


  • Remove support for macOS 10.15

Bolt 3.22.1 (2022-03-30)

Bug fixes

  • Fix codesigning error for macOS packages

Previously, Bolt would fail when making SSH connections when run on
macOS due to Bolt's packaged Ruby being erronously codesigned. Bolt
packages no longer codesign Bolt's packaged Ruby.

Bolt 3.22.0 (2022-03-28)

New features

  • Warn when bolt-plugin.json is found

Bolt will now warn if, while loading plugins, it finds a
bolt-plugin.json file in a module. The correct filename is
bolt_plugin.json, and Bolt will advise renaming the file in order for
it to be loaded.

Contributed by Lucy Wyman

  • Allow reading manifests from a named pipe

Bolt will now read manifests from a named pipe, treating them as

Contributed by Jesse Hathaway

  • Configure path to the rerun file

You can now configure the path to Bolt's rerun file at the project
level with the new rerunfile config option.

  • Option to parse data as JSON looked up with env_var plugin

The env_var plugin now accepts a json option to allow
the plugin to use data encoded as JSON stored in environment

Bug fixes

  • Make native-ssh more portable

Updates native-ssh so setting batch-mode: false omits -o BatchMode= and adds a double-dash separater -- before commands to

  • Support resolving facts from nested arrays with puppetdb plugin

Previously, indexing into arrays when resolving values from puppetdb
facts using the target_mapping for the puppetdb plugin did not work.
This is now possible by specifying the index of the array, for example:

Bolt 3.21.0 (2021-12-16)

New features

  • policies configuration setting

The project configuration file, bolt-project.yaml, has a new
policies setting which lists the configuration policies available to
a project.

This feature is experimental and subject to change.

  • policy subcommands

Bolt now includes three new subcommands for interacting with a
project's configuration policies:

  • The policy new command can be used to create a new configuration
    policy in the project and add it to the project's configuration.
  • The policy show command can be used to view which configuration
    policies are available to a project.
  • The policy apply command can be used to apply one or more
    configuration policies to a list of targets.

This feature is experimental and subject to change.

Bolt 3.20.0 (2021-10-26)

New features

  • Support arrays and strings for interpreters transport configuration

Bolt now supports arrays in addition to strings as the value for the
interpreters transport configuration option, which enables passing
flags in addition to a binary.

Bug fixes

  • Resolve puppetdb client configuration plugins as needed

Bolt now only resolves plugins for the puppetdb client when needed.
Previously, Bolt would attempt to resolve plugins for the puppetdb
client for every command, which would cause Bolt to error if the
plugin module was not available, such as when installing a project's
modules for the first time.

Bolt 3.19.0 (2021-10-04)

New features

  • Debian 11 packages

Bolt now ships packages for Debian 11.

  • Update bundled modules to latest versions

The following bundled modules have been updated to their latest

Bug fixes

  • Correctly set inventory config when resolving plugins

Previously, Bolt would resolve plugins then set the config in the
Inventory to nil, causing errors like undefined method 'merge' for nil:NilClass. Bolt now correctly returns the resolved config to the

Bolt 3.18.0 (2021-09-20)

New features

  • Support interpreters configuration when running scripts

Bolt now supports the interpreters transport configuration when running
scripts. To enable this feature, set the future.script_interpreter
configuration to true.

  • Create .gitignore in new projects with local Bolt files

The bolt project init command now lays down a .gitignore file to ignore
local files that Bolt creates while executing.

  • Update bundled modules to latest versions

The following bundled modules have been updated to their latest

Bolt now supports using a token to authorizing requests to the Forge when
installing modules using the module-install.forge.authorization_token

  • Look for scripts in a scripts directory

Bolt now looks for scripts in a project's or module's scripts directory when
provided a Puppet file path with the form <module>/scripts/<file>.
Previously, this behavior was opt-in only by setting the future.file_paths
configuration option.

Bug fixes

  • Return exit code 1 instead of 2 when Bolt errors

Bolt will now exit with code 1 instead of 2 whenever a Bolt operation fails.

  • Update BoltSpec functions to allow absolute paths

BoltSpec's allow_upload, expect_upload, allow_script, and
expect_script functions now support passing absolute paths that rather than
a module reference. The referenced path must refer to a real file or upload
and script functions will still error.

  • Correctly set main plan ID

Bolt now sets the main plan's ID to the correct value. Previously, the main
plan ID was set incorrectly, causing Bolt to issue warnings during plan runs
when it should not have.

  • Allow using the scripts file mount in Puppet manifests

This fixes a bug where scripts/ directory files needed for the new Puppet
scripts mount were not included in the tarball of dependencies for applying
manifests. Users can now use the scripts mount from Puppet manifests.


  • Deprecate future.file_paths configuration option

The future.file_paths configuration option has been deprecated.

Bolt 3.17.0 (2021-08-30)

New features

  • Pass --script to bolt plan new to wrap a script in a plan (hack)
    The bolt plan new command now accepts a --script SCRIPT parameter
    that will generate a plan that simply runs the script and returns the
    result. The flag only supports detailed (new-style) Puppet file
    references. Learn more about file references at

Bug fixes

  • Do not wrap commands in sh -c when not using environment variables
    or privilege escalation

Bolt no longer wraps commands in sh -c when environment variables
are not specified and not using privilege escalation. Previously, Bolt
would wrap all commands in sh -c when using the SSH transport, which
caused commands to fail on targets that do not recognize sh, such as
some Windows targets.

  • Resolve plugins as needed

Bolt now only resolves plugin configuration, plugin hooks, and
inventory plugins as needed. Previously, Bolt resolved all plugins
each time a command was run, causing some commands to fail when
they should not.

Bolt 3.16.1 (2021-08-16)

Bug fixes

  • Handle empty response bodies in http_request task

The http_request task no longer errors when a response does not
include a body.

  • Fix stacktrace for conflicting module add and Puppetfile

When a project's Puppetfile has a forge module without a version specified,
Bolt now offers a more helpful error when attempting to do a module install/add of
the same module.

Bolt 3.16.0 (2021-08-09)

New features

  • Continue executing when a plan over PCP restarts the Orchestrator

Bolt will now retry a task once when running over PCP as part of a
plan, if the task errors with plan-already-finished.

Bug fixes

  • Do not remove variables from scope when using parallelize()

Bolt no longer removes variables from a plan's scope when invoking
a custom Puppet language function that invokes a run_* function from
a parallelize() block. Previously, a race condition would result in
the current plan's variables to be removed from the plan's scope.

  • Attempt to restore Ruby environment on local with bundled-ruby false

When executing, Bolt will unset several Ruby environment variables in
it's own environment to avoid unexpected behavior. This can interfere
with running Ruby on the local transport with Bolt though. Bolt will now
attempt to restore Ruby environment variables like GEM_HOME and
GEM_PATH when running over the local transport with bundled-ruby set
to false.

Bolt 3.15.0 (2021-08-02)

New features

  • Add ability for --clear-cache to clear plan/task metadata cache.

--clear-cache flag now clears plan/task metadata cache.

  • Support _catch_errors in apply_prep

The apply_prep function now accepts the _catch_errors parameter.
Additionally, the bolt apply and Invoke-BoltApply commands set
_catch_errors to true, allowing an apply action to complete on as
many targets as possible instead of erroring if even one target fails
the apply_prep portion of the command.

  • Respect @api tag in Puppet language plans

Bolt now respects the @api tag in Puppet language plans. If the
@api private tag is present, the plan will be hidden from bolt plan show and Get-BoltPlan output.

Bug fixes

  • Ship with Bolt guides

Bolt 3.14.1 neglected to updated the bolt.gemspec to include new
guide files. This updates the gemspec to include the new guide files.


  • Deprecate @private tag in Puppet language plans

The @private tag for Puppet language plans is deprecated. Use the
@api tag instead.

Bolt 3.14.1 (2021-07-26)

New features

  • wait() without arguments waits on all Futures from plan

Calling the wait() plan function without a list of Futures will now
wait on all Futures created so far in the plan.

  • Ship puppetlabs/http_request 0.3.0

Bolt now ships with the latest version of the http_request module,
which includes support for making patch requests.

  • YAML plan verbose step

YAML plans now support a verbose step that prints a message
when run in verbose mode.

  • Log messages from out::message and out::verbose

The out::message plan function now logs messages at the info level
and the out::verbose plan function now logs messages at the debug
level. Both functions continue to print messages to the console.

  • Show detailed module information

Bolt now supports showing detailed information about a module using
the bolt module show <module> command and Get-BoltModule -Name <module> PowerShell cmdlet.

  • Beautify bolt guide output

This converts our existing guides from flat text to YAML so that they
can be pretty printed.

  • Add batch-mode configuration option for native-ssh transport

The native-ssh transport has a new batch-mode configuration option
that can be used to enable or disable BatchMode. For more
information, see the

  • Format PlanResults if they are Bolt datatypes

Bolt will now print a more human readable message for plan results
that are Bolt datatypes when using the human output format, rather than
printing JSON.

Bug fixes

  • Do not warn about analytics when analytics is disabled

Bolt no longer displays a warning about analytics collection when
analytics is disabled and the analytics.yaml file does not exist.


  • Remove support for Fedora 30, Fedora 31, and MacOS 10.14

Bolt 3.13.0 (2021-07-12)

New features

  • Add built-in log module

Bolt now ships with a new built-in log module that includes plan
functions for logging messages at each of Bolt's log levels. The new
plan functions include log::trace, log::debug, log::warn,
log::info, log::error, and log::fatal.

  • Fedora 34 packages

Bolt now ships packages for Fedora 34.

  • Add out::verbose plan function

Bolt now has out::verbose plan function, which allows for
printing output when run in verbose mode.

Bolt 3.12.0 (2021-07-06)

New features

  • Support macOS 11 in `puppet_agent::install task

The puppet_agent::install task now supports installing the
puppet-agent package on macOS 11.

  • Disable 'exported resources' warnings from Puppet

Warnings logged by Puppet when declaring or collecting exported
resources in a manifest can now be disabled. To disable these warnings
add the exported_resources ID under the disable-warnings
configuration option.

Bug fixes

  • Do not stacktrace with non-existent files in plan or task cache

Bolt no longer errors with a stacktrace when listing plans or tasks
when the plan or task cache include paths to files that no longer

Bolt 3.11.0 (2021-06-21)

New features

  • macOS 11 packages

Bolt now ships packages for macOS 11 (Big Sur).

  • Update bundled modules to latest versions

The following bundled modules have been updated to their latest

Bolt now ships with Puppet 7.7.0.

Bug fixes

  • Handle printing command and script results with no output

Bolt no longer errors when printing results from a command or script when the
result does not include output on stdout or stderr. Previously, Bolt would
error with an undefined method message.

  • Handle printing command and script results with pcp transport

Bolt no longer errors when printing command and script results when using the
pcp transport. Previously, Bolt would error with an undefined method

  • Install modules when using Bolt as a gem

Bolt no longer errors when installing modules using the bolt gem.
Previously, Bolt would error with a missing parameter message.

Bolt 3.10.0 (2021-06-14)

New features

  • Add plugin show command

The bolt plugin show command and Get-BoltPlugin PowerShell cmdlet
can be used to list plugins available to the current project.

  • Lookup hiera plan_hierarchy values from the CLI

The bolt lookup command now has a --plan-hierarchy flag that will
lookup values from Hiera's plan_hierarchy.

  • New Bolt debugging guide

Bolt has a new guide with common debugging tips that can be accessed
by running bolt guide debugging.

  • Builtin tab completion

Bolt now supports tab completion for Bolt commands, subcommands, and
any flags available for a command. It also supports tab completing tasks
and plans for certain project types when tasks and plans have been

Bug fixes

  • Test plans that use parallelize() plan function in BoltSpec

BoltSpec no longer fails when testing plans that include the
parallelize() plan function. Previously, testing plans that used
this function would cause the plan to fail with an argument mismatch

  • Pass remaining arguments to PowerShell -Arguments parameter

The PuppetBolt PowerShell module now correctly supports passing
multiple arguments to the -Arguments parameter. Previously, any
unbound arguments were not passed to this parameter, causing the
PowerShell parser to error.


  • PuppetBolt PowerShell module will not ship with Bolt packages in a
    future release


The PuppetBolt PowerShell module will no longer ship with Bolt
packages on Windows in a future release. The PuppetBolt PowerShell
module should instead be installed from PowerShell Gallery.

Bolt 3.9.2 (2021-06-08)

Bug fixes

  • Do not error when using --run-as on a Windows controller

Bolt no longer raises an error when using the --run-as command-line
option on a Windows controller.

Bolt 3.9.1 (2021-06-07)

New features

  • Ship PuppetBolt PowerShell module to PowerShell Gallery

The PuppetBolt PowerShell module is now shipped to the PowerShell
. For more
information about installing the PuppetBolt PowerShell module, see the

  • Report whether tasks are run in no-operation mode

Bolt now reports whether or not a task is run in no-operation mode when it
collects analytics.

Bug fixes

  • Provide project for BoltSpec::Run::Runner#pal

Fixes a project null reference in the invocation of the download_file()
function in a plan driven by the BoltSpec::Run runner.

  • Undef variables are now included in Future block scopes

Previously, Bolt would not include variables with a value undef in Future
block scopes, leading them to be undefined. Bolt now includes those variables
when creating the new scope for Future blocks.

Bolt 3.9.0 (2021-05-25)

New features

  • Plan functions to support fire-and-forget parallelism

Bolt now includes two new plan functions, background() and wait(), to
support fire-and-forget parallelism.

  • Support run-as for container transports when running on nix

The Docker, LXD, and Podman transports now support run-as
configuration and related configuration options when running on nix
systems. run-as is not supported for any Windows systems or the
PowerShell shell over SSH.

Bug fixes

  • Upload project plugin files to correct directory when running an


Project plugin files are now uploaded to the correct directory when
running an apply. Previously, if a project used a Boltdir or had a
directory name that did not match the project's configured name, apply
blocks could not correctly reference files in the project using Puppet
file syntax (puppet:///modules/<project name>/<file name>).

  • Correctly set DOCKER_HOST environment variable when connecting
    to remote Docker hosts


Bolt now correctly sets the DOCKER_HOST environment variable when
the docker.service-url configuration is set. Previously, this
environment variable was not set correctly, preventing the transport
from connecting to remote Docker hosts.

Contributed by Mic Kaczmarczik

Bolt 3.8.1 (2021-05-17)

Bug fixes

  • Support _run_as passed to apply_prep()

Bolt now respects the _run_as metaparameter when passed to the
apply_prep() plan function. This is the only supported metaparameter, and
takes highest precedence per the Bolt configuration

  • Don't stacktrace if welcome message file can't be written

Previously, Bolt would stacktrace if it failed to make the directory to store
the welcome message file in, which relies on tilde ~ expansion. Bolt now
falls back to a system-level path, and then omits the welcome message entirely
if the system-level path also fails to be created or written to.

  • Do not error in file::* plan functions when future is not configured

The file::exists, file::read, and file::readable plan functions no
longer error when invoked outside of an apply block when future is not


  • JSON output documentation

The format for JSON output for each of Bolt's commands is now

Bolt 3.8.0 (2021-05-03)

New features

  • Facts diff task accepts exclude parameter

The puppet_agent::facts_diff task now accepts an exclude parameter
to filter output based on a provided regex.

  • lookup command to look up values with Hiera

The new bolt lookup and Invoke-BoltLookup commands can be used to
look up values with Hiera.

  • Load files from specified Puppet paths

If the project-level future.file_paths configuration is enabled,
Puppet files can be loaded using the new loading syntax. For more
information see


  • Puppet5 collection no longer available for puppet_agent::install


Now that this collection is unavailable to download from, it's not a
valid parameter to the puppet_agent::install task.

Bolt 3.7.1 (2021-04-26)

New features

  • Developer Update: Script loading changes

There's a new Developer Update in town, read it

Bug fixes

  • Allow Docker connections using full ID as the host

The Bolt Docker transport now successfully connects to containers
when the full SHA 256 container ID string is provided as a name or
URL. Previously, Bolt could only connect when the 12 character
shortened form of the ID string was used.

  • Fixed incorrect param in Get-BoltTask text (#2795)

Fixed the 'Additional Information' section of the help text for the Get-BoltTask cmdlet having an
incorrect parameter for the task name

Contributed by Malivil

Bolt 3.7.0 (2021-04-13)

New features

  • Default to showing all targets with bolt inventory show

The bolt inventory show and Get-BoltInventory commands now default
ot showing all targets in the inventory if a targetting option
(--targets, --query, --rerun) are not provided.

  • Improved group information output

The bolt group show and Get-BoltGroup commands now display human
output in a similar format to other show commands. The json output
now includes the path to the inventory file that the groups are loaded

  • puppetdb_command plan function

The puppetdb_command plan function can be used to invoke commands in
PuppetDB. Currently, only the replace_facts command is officially
tested and supported, though other commands might work as well.

This feature is experimental and subject to change.

Bug fixes

  • Do not error when using metaparameters in YAML plans

Bolt no longer errors for YAML plans that include a plan or task step
that includes an additional option (e.g. _catch_errors) under the
parameters key.

  • Output correct inventory source with inventory show

The bolt inventory show and Get-BoltInventory commands now output
the correct source of inventory when using the BOLT_INVENTORY
environment variable. Previously, Bolt would output the path to the
default inventory file.

Bolt 3.6.1 (2021-04-07)

Bug fixes

  • Ensure all messages print, even after thread finishes

Bolt now ensures that all messages from a command or script are
printed back to the user. Previously, some messages would be lost
if they were read after the thread finished executing or when Bolt had
been prompted for a sudo password.

Bolt 3.6.0 (2021-04-06)

New features

  • Improved inventory output

The bolt inventory show and Get-BoltInventory command now display
human output in the same format as other show commands.

  • Improved plan and task information output

The bolt plan|task show <name> and Get-Bolt(Plan|Task) -Name <name> commands now display human output in a similar format to
other show commands.

  • Podman transport

The Podman transport connects to local running Podman containers,
useful for testing scenarios or debugging.

  • Disable analytics in system, user, and project config files

The new analytics configuration option can be used to disable data
collection in Bolt and is supported in both bolt-defaults.yaml and
bolt-project.yaml. Disabling data collection cannot be overridden by
enabling it in another configuration file.

Bug fixes

  • Do not stack trace when missing project configuration file

Bolt no longer stack traces when installing modules if the project
does not have a bolt-project.yaml configuration file.

Bolt 3.5.0 (2021-03-29)

New features

  • Test plans that use run_task_with() plan function in BoltSpec

Plans that use the run_task_with() plan function can now be tested
with BoltSpec.

  • run_container() plan function

Bolt now ships with a run_container() Puppet plan function that will
run a container and return its output.

  • Update bundled modules

The following bundled modules have been updated to their latest

Bug fixes

  • Do not warn on top level plugin_hooks config

Bolt no longer warns that plugin_hooks are an unknown option when configured
in inventory file.

  • Allow version key in inventory files

Bolt now recognizes the version configuration in an inventory file
and doesn't raise a warning that the key is unknown.


  • Deprecate dotted fact names

Dotted fact names (e.g. are now deprecated. Bolt issues a
deprecation warning if it detects a target is loaded with these facts
or has them added during a plan run.

Bolt 3.4.0 (2021-03-23)

New features

  • Display merged stdout and stderr output for commands and scripts

The bolt command|script run commands and Invoke-BoltCommand|Script
cmdlets now display merged output from stdout and stderr in the CLI.
This merged output is also available to the Result object in plans
and in the JSON output format under the merged_output key.

  • Convert YAML plans by name

The bolt plan convert and Convert-BoltPlan commands now accept the
name of a YAML plan to convert instead of just a path to a YAML plan.

  • Add default value for prompt plan function

The prompt plan function has a new default option which can be
used to return a default value when a user does not provide input
or when stdin is not a tty.

  • LXD transport supports remote hosts

The LXD transport includes a new remote option to configure
connections to remote LXD servers.

  • Add welcome message when users first run Bolt

Bolt now prints a welcome message when users first run Bolt if they run
bolt, bolt --help, or bolt help.

  • prompt::menu plan function

The new prompt::menu plan function can be used to prompt the user to
select an option from a menu of options.

  • Upgrade bundled modules

The following bundled modules have been updated to their latest

Bug fixes

  • Ensure env_vars is a hash in commands and scripts

Bolt now ensures that the env_vars option passed to commands and
scripts in plans is a hash and will raise a helpful error message

  • Convert env_vars hash values to JSON

Bolt now converts hash values for an environment variable passed to a
command or script to JSON. Previously, a hash value would be passed
with Ruby-style syntax.

  • Don't stacktrace when showing tasks that include untyped parameters

Bolt will now correctly show task details for tasks that include
parameters that do not specify a type, instead of stacktracing.

  • Do not error when showing 'noop' task info

Bolt no longer errors when printing task information for a task that
supports running in no-operation mode.

  • Handle malformed _error values in task results in Orchestrator

Bolt now handles _error from task results in the Orchestrator
transport when the value of the key is not a hash, does not include the
details key, or the details key is not a hash. Previously Bolt would
error if any of these conditions was true.

Bolt 3.3.0 (2021-03-15)

New features

  • Add LXD transport

Bolt now includes a new LXD transport to use when connecting with containers
managed with LXD. See the transport configuration

for configuration options. This feature is experimental and might change
between minor versions.

Contributed by Coleman McFarland

  • Stream output from targets

You can now stream output from a target as actions are running using the
stream configuration option or the --stream command-line option. For more
information, see the
This feature is experimental and might change between minor versions.

  • Support metaparameters as top-level keys in YAML plan steps

YAML plan steps now support metaparameters as top-level keys. For
example, the script step supports an env_vars key which accepts a
hash of environment variables to set on the target when running the

  • Show plan descriptions in plan list

Plan descriptions now appear in bolt plan show and Get-BoltPlan

  • Support Puppet paths when running scripts from the CLI

You can now use Puppet paths (<MODULE NAME>/<FILE NAME>) to specify
the path to a script when running bolt script run or

  • Add pwsh_params option to run_script plan function

The run_script plan function now accepts a pwsh_params option
which can be used to pass named parameters to a PowerShell script.

  • Upgrade bundled modules to latest versions

Several of Bolt's bundled modules have been upgraded to their latest
versions. Some modules have been upgraded to new major versions, which
are not compatible with Puppet 5. Bolt officially dropped support for
Puppet 5 in Bolt 3.0.

The following modules have been upgraded to new major versions:

The following module has been upgraded to the latest version and is
still compatible with Puppet 5:

Bolt now reports whether a file path is an absolute path or a Puppet file path
for the run_script, file::read, and upload_file plan functions.

Bug fixes

  • Handle plan parameter tags without descriptions

Bolt no longer errors if a plan includes a Puppet strings @param tag
that does not have a description.

  • Run YAML plan plan steps with targets key

YAML plans that have a plan step with a top-level targets key now
pass the targets to the plan.

  • Test YAML plans with BoltSpec

YAML plans can now be tested with BoltSpec.

  • Convert YAML plans with a null eval step

YAML plans that include a null eval step no longer raise an error
when converted to a Puppet language plan.

  • Correctly read SSL key contents in http_request task

The http_request now correctly reads key contents from the path passed to
the key parameter. Previously, the task used the file path itself as the key

  • Support run-as configuration when downloading files

The run-as configuration for the SSH transport is now supported when
downloading files.

  • Do not send task parameters over stdin when using a tty

Tasks with a stdin input method that are run on targets with tty: true configuration no longer return the task's parameters as part of
the task output. Previously, Bolt was sending these parameters to the
task twice, causing them to be printed to standard out (stdout) and
returned in the task output.

Bolt 3.2.0

This version of Bolt was not released.

Bolt 3.1.0 (2021-03-01)

New features

  • Add Bolt Task directory to PSModulePath

Add the bolt task target directory to the PSModulePath to allow Bolt tasks to
ship powershell modules that can be automatically imported

  • Ship with puppetlabs/powershell_task_helper module

Bolt now ships with the puppetlabs/powershell_task_helper module, which
includes helpers for writing tasks in PowerShell.

  • Added config_data helper to BoltSpec library

The BoltSpec library includes a new config_data helper which can be used
to set Bolt configuration in your plan unit tests.

Bug fixes

  • Support Puppet file syntax for files in a Bolt project

Bolt now supports Puppet file syntax (puppet:///modules/<MODULE>/<FILE>) in
apply blocks for files in a Bolt projec. Previously, apply blocks would not
compile if using this syntax for files in a Bolt project.

  • Serialize Sensitive task output for Result.to_data method

Previously, the to_data method on a Result object did not transform
Sensitive task output. Now, the to_data method serializes the output by
calling the to_s method on Sensitive output, which will simply print a
"value redacted" message.

  • Improve error messages for bolt script in PowerShell

Errors raised from running scripts in PowerShell on targets with an execution
policy of Restricted or AllSigned now include clearer messages.

  • Expose inventory to BoltSpec stubs and mocks

Stubs and mocks that use the return_from_targets modifier now have access to
Bolt's inventory. Previously, the inventory was not exposed to these stubs and
mocks, resulting in 'Undefined method' errors.

Bolt 3.0.1 (2021-02-16)

Bug fixes

  • Install Puppetfile without modules configured

Bolt now correctly installs a Puppetfile with bolt module install --no-resolve and Install-BoltModule -NoResolve even if the
modules key is not configured or is an empty array.

  • Fix PowerShell Cmdlet Version detection (#2636)

PowerShell users can now run Get-BoltVersion to list the Bolt version. This, and bolt --version should both load more quickly.

Bolt 3.0.0 (2021-02-03)

New features

  • Ship with Puppet 7

The Bolt gem and Bolt packages now ship with Puppet 7.

  • Use bolt.bat for execution on Windows

This removes the bolt PowerShell function and instead relies on a new
bolt.bat file that is included in Bolt packages.

  • Update default modulepath

Bolt's default modulepath is now ['modules'] instead of ['modules', 'site', 'site-modules']. Bolt will also automatically append the project's
.modules/ directory to all modulepaths, whether a project uses the default
modulepath or a configured modulepath.

  • Improve bolt powershell task error message

Format the exception powershell type tasks throw to make it easier for a user
to read the error message.

  • Local transport's bundled-ruby option defaults to true

The local transport's bundled-ruby configuration option, which determines
whether to use the Ruby bundled with Bolt packages for local targets, now
defaults to 'true' instead of 'false'. The option can still be configured as

  • Ship with puppetlabs/stdlib 6.6.0

Bolt packages now ship with the latest version of the puppetlabs/stdlib

Bug fixes

  • Include plan name in missing_plan_parameter warnings

The missing_plan_parameter warning now includes the name of the plan
that the message was logged for.


  • Remove support for the bolt.yaml configuration file

The bolt.yaml configuration file is no longer supported by Bolt. Use
bolt-project.yaml and bolt-defaults.yaml instead.

  • Remove support for Debian 8

Bolt no longer builds or tests packages for the Debian 8 platform.

  • Remove support for puppet-agent < 6.0.0

Bolt no longer supports puppet-agent versions earlier than 6.0.0.
While applying Puppet code to targets with earlier versions of the
puppet-agent package installed may still succeed, Bolt no longer
guarantees compatibility.

  • Remove support for PowerShell 2.0

Bolt no longer supports PowerShell 2.0 on the controller or on
targets. While running commands and tasks in PowerShell 2.0 may
still succeed, Bolt no longer guarantees compatibility.

  • Remove deprecated command-line options

The --boltdir, --configfile, --debug, --description, and
--puppetfile command-line options have been removed.

  • Remove deprecated configuration options

The apply_settings, inventoryfile, plugin_hooks, and
puppetfile configuration options have been removed.

  • Remove notice log level

Bolt no longer accepts notice as a log level, via the command line
or configuration. Use info instead.

  • Remove bolt puppetfile subcommand

Removes the bolt puppetfile * and *-BoltPuppetfile subcommands. Use
the bolt module * and *-BoltModule subcommands instead.

  • Remove support for private-key, public-key parameters in pkcs7 plugin

Support for the private-key and public-key parameters in the pkcs7
plugin has been removed. Use the private_key and public_key
parameters instead.

  • Remove source and target YAML plan step keys

Support for the source and target keys in YAML plans has been
removed. Use upload and targets instead.

  • Remove aggregate::nodes plan

Bolt no longer ships with the aggregate::nodes plan. Use the
aggregate::targets plan instead.

Bolt 2.44.0 (2021-01-27)

New features

  • Hide private plans from bolt plan show and Get-BoltPlan

Users can now set the top-level private key in YAML plans, or the @private
Puppet string, to mark a plan as private.

  • Add read-timeout configuration option for PCP transport

Users can now configure a read-timeout for HTTP requests to the
Orchestrator, which defines how long to wait for a response before raising a
Timeout error.

  • Support additional Puppet settings in apply-settings

The log_level, trace, and evaltrace Puppet settings can now be
configured under the apply-settings configuration option. These settings
will be applied when executing an apply block.

  • Add resolve key for Forge and git module specifications

Forge and git module specifications in bolt-project.yaml now support a
resolve key. When setting resolve: false, Bolt will skip dependency
resolution for the module, allowing users to include modules with broken
metadata or modules hosted in a repository other than a public GitHub
repository in their project configuration.

  • Bolt modules usable with Puppet 7

Modules owned by the Bolt team now have a maximum Puppet version of 8, so are
usable with Puppet 7 on the Bolt controller.

  • Suppress warnings with disable-warnings config option

The disable-warnings configuration option accepts an array of warning IDs
that are used to suppress warnings in both the CLI and log files. This
configuration option is supported in both bolt-project.yaml and

Bug fixes

  • Only spin while executing run_* plan functions

Bolt will now only print the spinner while executing run_*, file_upload,
file_download, andwait_until_available plan functions. It also now spins
while running those functions equivalent commandline commands. This prevents
the spinner from spinning while prompting for output from a plan.

  • Correctly shadow fact/variable collisions in apply blocks

Bolt now correctly shadows target and plan variables that collide with facts
of the same name when running apply blocks.

  • Don't continue executing parallel block when prompting

Bolt will now pause printing messages from parallel blocks when prompting the
user for input, to avoid confusing printing to the screen.

Bolt 2.42.0 (2021-01-11)

New features

  • Support module-install config when resolving modules

The bolt module add|install commands and Add|Install-BoltModule
cmdlets now support the module-install config option when resolving
module dependencies.

  • Updated bundled modules to latest version

The following bundled modules have been updated to their latest

Bolt now supports project-level plugins. Similar to module plugins,
project-level plugins are implemented as tasks that use specific hooks
and are referred to using the name of the project.

Bug fixes

  • Allow entire inventory to be specified with a plugin

Inventory files can now be specified with a plugin. For example, the
following inventory file is now valid:


_plugin: yaml
filepath: /path/to/inventory_partial.yaml

  • Delete transport config keys that resolved to nil

Previously, if a plugin reference resolved a transport config key to nil
Bolt would still include that key in the target's transport config. This
change ensures that nil-resolved transport config keys are deleted during
inventory parsing.

  • Don't stacktrace when converting YAML plans with errors

Bolt will now error cleanly instead of stacktracing when users try to
convert a YAML plan that has type or syntax errors.


  • Deprecate puppetfile in favor of module-install

The puppetfile configuration option has been deprecated in favor of
module-install and will be removed in Bolt 3.0. Users should update
their projects to use the module management feature, which uses the
module-install option.

  • Deprecate puppetfile commands

The bolt puppetfile * commands and *-BoltPuppetfile cmdlets have
been deprecated and will be removed in Bolt 3.0. Users should update
their projects to use the module management feature, which uses the
bolt module * commands and *-BoltModule cmdlets.

Bolt 2.40.2 (2020-12-18)

Bug fixes

  • Only print spinner when stdout is a TTY (#2500)

We now only print the spinner when the STDOUT stream is a TTY.

  • Do not add localhost target to the all group by default in


Bolt no longer adds the localhost target to the all group by
default. Previously, when running Bolt in PowerShell, the localhost
target would be added to the all group unintentionally.

Bolt 2.40.1 (2020-12-16)

Bug fixes

  • Fix bug warning about keys under 'remote' transport

Bolt now will not warn when keys are configured for the remote
transport in inventory.

  • Support plugins for suboptions under options that allow plugins

All suboptions for config options that support plugins once again
support plugins. For example, the key-data suboption for the
private-key option can use plugins again.

  • Load the correct data for plugin invocations

Bolt now correctly loads data for the plugin invocation based on the
plugin data, not just cache ttl. Previously, any plugins with the
same cache configuration would collide in the cache data and overwrite
each other, causing the wrong data to be loaded.

Bolt 2.38.0 (2020-12-14)

New features

  • bundled-ruby local transport config option to enable local defaults

Set bundled-ruby in the local transport config to enable or disable
the default config currently used for the localhost target.

  • module-install configuration option

Bolt now supports a module-install configuration option in
bolt-project.yaml and bolt-defaults.yaml. This option is used to
configure proxies and an alternate forge when installing modules using
the bolt module add|install commands or Add|Install-BoltModule

This option is not currently supported when resolving module

  • Improved inventory validation

Bolt now validates inventory against Bolt's inventory schema and
indicates where errors are found.

  • CLI spinner for long running operations

Bolt now has a spinner printed to the CLI for long-running operations,
so that users know the Bolt process has not hung. Disable the spinner
by setting spinner: false in any Bolt configuration file.

  • JSON schema for YAML plans

Bolt now offers a JSON schema for validating YAML plans.

Bug fixes

  • Windows local transport returns correct exit codes and accepts pipes

When running commands over the local transport on Windows machines,
Bolt now returns the exit code returned by the command as opposed to
just 0 or 1. It also accepts pipes as part of the command.

  • Accept plugins in puppetdb config

Fixes a regression to once again allow plugins to be used for defining
the values of the puppetdb config.

Contributed by Nick Maludy

  • Only warn that project content won't be loaded if there's project content

Bolt will now only warn that project content won't be loaded if the
proejct directory has a tasks/, plans/, or files/ directory that
may contain content.

  • Allow caching for PuppetDB plugin

Previously, our configuration validation would raise an error if users
supplied _cache to the PuppetDB plugin. Cache is now configurable
for the plugin.

  • http_request task converts header names to strings

Headers set under the headers parameter are now converted to strings before
making a request. Previously, headers were passed to the request as symbols.

Contributed by barskern

Bolt 2.37.0 (2020-12-07)

New features

Bolt plugins can now be configured to cache their results. Users can either
configure a default cache time-to-live for all plugins, or configure each
plugin's TTL individually. See the documentation
for more information.

This feature is considered experimental.

Bug fixes

  • Support notice log level

Log levels can now be set to notice. Previously, Bolt would raise an
error saying that notice was not a supported log level.


  • Deprecate Powershell 2 support

Support for Powershell 2 on both Bolt targets and controllers is
deprecated, and will be dropped in Bolt 3.0.

  • Deprecate bolt.yaml

The bolt.yaml configuration file is now deprecated, both at
project-level and user/system-level.

  • Deprecate notice log level

The notice log level is deprecated and will be removed in Bolt 3.0.
Use the info log level instead.

Bolt 2.36.0 (2020-11-30)

New features

  • bolt plan new and New-BoltPlan commands no longer experimental

The bolt plan new and New-BoltPlan commands are no longer
considered experimental.

  • Module management workflow no longer experimental

The module management workflow is no longer considered experimental. For more
information, see the modules
in the Bolt

  • Configure modules with bolt project init

The bolt project init command will now configure the modules key
in the bolt-project.yaml file, enabling the bolt module command.

  • Create inventory.yaml file when creating new projects

The bolt project init and New-BoltProject commands now create an
inventory.yaml file in the new project.

  • Log plugin task output at trace level

Plugin task output is now logged at trace level.

  • Improved config validation

Bolt now validates config files against Bolt's schemas and indicates
which config file an error is found in.

  • Warn about unknown configuration options

Bolt now issues a warning when it detects an unknown configuration
option. The warning will indicate where the configuration option is

  • Added value() function to ApplyResult datatype

The ApplyResult datatype has a new value() function that returns a
hash that includes the Puppet report from an apply under the report

Bug fixes

  • Targets without a uri can now use apply() and get_resources()

Previously, if a target had a host set instead of a uri it would
error when trying to set the Puppet certname to the target's URI. We now
use the target's name instead of the uri as the Puppet certname when
compiling catalogs.

  • Allow loading SSH Config through net-ssh when using native-ssh to fail

As skipping loading SSH config through the net-ssh gem is not
feasible, we allow loading the ssh config to fail and fall back
to the inventory file settings or the logged in user.

Contributed by Robert Führicht

  • Ship puppet_agent manifests directory

Bolt now includes the puppet_agent module manifests directory and
it's classes in the Bolt gem and packages.


  • Deprecate --boltdir, --configfile, --puppetfile, and --description
    command-line options


We are planning to remove the --boltdir, --configfile,
--puppetfile, and --description command line flags in the next major
version of Bolt. This adds deprecation warnings that are printed when
users specify any of these flags.

  • Deprecate inventoryfile configuration option

The inventoryfile configuration option has been deprecated and will
be removed in Bolt 3.0. Users should move contents from non-default
inventory files to the inventory.yaml file in a Bolt project, or can
use the --inventoryfile command-line option to load a non-default
inventory file.

  • Deprecate plugin_hooks in favor of plugin-hooks

The plugin_hooks configuration option has been deprecated in favor
of plugin-hooks.

  • Deprecate apply_settings in favor of apply-settings

The apply_settings configuration option has been deprecated in favor
of apply-settings.

Bolt 2.35.0 (2020-11-16)

New features

  • Set default ports for PuppetDB and Orchestrator

Bolt now sets the ports for PuppetDB server_urls and Orchestrator
service-url to 8081 and 8143 respectively if the port is not set in config.

  • Filter project plans and tasks with glob patterns

The plans and tasks options in bolt-project.yaml now support glob
patterns in addition to plan and task names. Plans and tasks that match a glob
pattern will appear in bolt plan|task show and Get-Bolt(Plan|Task) output.

  • Execute plan functions in parallel with parallelize plan function

The new parallelize plan function can be used to execute part of a plan in
parallel. It accepts an array of inputs and a block, executes the block on
each input, and returns a list of results. This function can be used to
continue executing part of a plan across multiple targets without waiting on
results to finish for each target.

This feature is experimental.

Bug fixes

  • Error with invalid YAML plan step type

Bolt now errors if a YAML plan step is not a hash. Previously, YAML plans
would execute even if a plan step was not a hash.

Bolt 2.34.0 (2020-11-10)

New features

  • Create new Puppet language plans with --pp flag

Bolt can now create new Puppet language plans using the bolt plan new command
with the --pp flag or the New-BoltPlan PowerShell cmdlet with the -Pp

  • Show PowerShell cmdlets in output when running in PowerShell

Bolt output that includes commands will now show PowerShell cmdlets instead of
*nix shell commands when running in PowerShell.

Bug fixes

  • Fix complicated quoting in PowerShell Cmdlets

When using the Powershell cmdlets module, Bolt no longer wraps each command in
single quotes allowing users to successfully use more complicated quoting

  • Don't log task output from plugins

Bolt no longer logs the output from plugin tasks, to avoid printing
sensitive information to logs.

Bolt 2.33.2 (2020-11-04)

Bug fixes

  • Fix module name validation for Forge and Git module specifications

Forge and Git module specifications now correctly validate the
module's name and permit uppercase letters in the owner segment of the
module name. Previously, if the owner segment of a module name
included uppercase letters, Bolt would raise an error.

Bolt 2.33.1 (2020-11-02)

New features

  • Updated bundled modules to latest version

The following bundled modules have been updated to their latest

Errors raised when evaluating code in a YAML plan now include the path
to the YAML plan and the line number that the error occurred on in the

  • File and line number included in plan function errors

If the plan functions run_command, run_script, or run_task fail
they will now include the file and line number in the details key of
the Result object. This information will also be printed when run with
info level logging or higher.

Bug fixes

  • Safely delete tmpdir used to configure Puppet for PAL

Bolt now safely deletes the tmpdir used to configure Puppet when using
PAL. Previously, if the tmpdir was deleted during a Bolt run before
Bolt deleted the directory itself, an error with a stacktrace would be

  • Do not override SSL variables in PowerShell module

The PowerShell module no longer overrides the SSL_CERT_FILE and
SSL_CERT_DIR environment variables if they are already set.


  • Folded scalar values in YAML plans no longer evaluated

Folded scalar values in YAML plans are no longer evaluated and are
instead treated as string literals.

Bolt 2.32.0 (2020-10-26)

New features

  • Add json_endpoint parameter to http_request task

The http_request task now accepts a json_endpoint parameter. When set to
true, the task will convert the request body to JSON, set the Content-Type
header to application/json, and parse the response body as JSON.

  • Git module support for module management feature

Git modules can now be specified in bolt-project.yaml and used with
the module management feature. Only GitHub modules are supported.

Bug fixes

  • Fix 'method not found' error when showing inventory

Previously, when running bolt inventory show or Get-BoltInventory with a
configured inventory path and the human format a 'method not found' error was
raised. This now correctly prints the targets in the inventory.

  • Handle printing preformatted Puppet errors with out::message

The out::message plan function now correctly prints preformatted
Puppet errors. Previously, printing preformatted Puppet errors would
result in a 'stack level too deep' error.

Bolt 2.31.0 (2020-10-19)

New features

  • Improved output for bolt inventory show and Get-BoltInventory

The bolt inventory show command and Get-BoltInventory cmdlet now show if a
target was not found in inventory. Output also includes the path to the loaded
inventory file and the number of inventory targets and adhoc targets.

  • Print changes made to Puppetfile when adding modules

The bolt module add command and Add-BoltModule cmdlet now display
a message describing changes made to the Puppetfile, including modules
that have been added, removed, upgraded, or downgraded.

  • Update bundled modules to latest versions

The following bundled modules have been updated to their latest

Bug fixes

  • Log when default inventory file cannot be loaded

Bolt now logs that it tried but failed to load the default inventory
file when the default inventory file does not exist. Previously, Bolt
would log that it loaded the default inventory file, even when it was
unable to do so.

  • Add moduledir directive to generated Puppetfile

Puppetfiles generated using the bolt module install command and
Install-BoltModule cmdlet did not include the moduledir directive.

Bolt 2.30.0 (2020-09-30)

New features

The new bolt module subcommand and modules key in project configuration
can be used to manage a project's module dependencies, including resolving
dependencies and version ranges. To learn more about managing a project's
module dependencies with Bolt, see the
. To read about why we added this
feature, see the developer

This feature is experimental.

  • HTTP request task

Bolt now ships with the http_request module, which includes the
http_request task for making HTTP requests.

Bug fixes

  • Show missing module dependencies when resolving modules

Bolt now correctly displays the names of missing module dependencies when
resolving modules errors. Previously, if a module dependency was missing, Bolt
did not display the name of the missing module.

  • Invalid YAML plans now fail gracefully

Previously, if a YAML plan had a syntax error Bolt would stacktrace due to an
assumption about what methods the resulting error had. It now fails gracefully
with the line of the error.

Bolt 2.29.0 (2020-09-21)

New features

  • Read command from a file or stdin using bolt command run

The bolt command run command can now read a command from a file or

Bug fixes

  • Reliably initialize logger with Bolt log levels

Bolt now checks whether the logger includes all of Bolt's log levels
if the logger has already been initialized.

Bolt 2.28.0 (2020-09-16)

New features

  • Define Hiera data to be looked up outside apply blocks under plan_hierarchy key (#1835)

Previously, Bolt used the same Hiera hierarchy for lookups inside and
outside apply blocks. Interpolations are only supported in apply blocks,
so if a hierarchy included interpolations the user could not look up
data outside an apply block. Users can now define a separate, statically
configured hierarchy in their Hiera config to be used outside apply

Bug fixes

  • Fix warning when running from a gem install

    Bolt again properly detects when it's being run from a gem install
    and emits a warning.

  • Fix error 'no method found trace' error when running BoltSpec

    There was one place where we didn't properly initialize the Bolt logger, causing a stacktrace
    in some BoltSpec uses. We now properly initialize the Bolt logger.


March 13, 2023, midnight
Register or login to:
  • 🔍View and search all Bolt releases.
  • 🛠️Create and share lists to track your tools.
  • 🚨Setup notifications for major, security, feature or patch updates.
  • 🚀Much more coming soon!
Continue with GitHub
Continue with Google