You can use Bolt commands to connect to targets and perform actions on them. These actions range in complexity from invoking a simple command to running a series of commands and tasks as part of an orchestration workflow.
For a full list of available Bolt commands, see the Bolt command reference.
Bolt can run arbitrary commands on targets. To run a command, provide a command and a list of targets to run the command on.
*nix shell command
bolt command run 'pwd' --targets servers
PowerShell cmdlet
Invoke-BoltCommand -Command 'Get-Location' -Targets servers
🔩 Tip: If a command contains spaces or special shell characters, wrap the command in single quotation marks.
If you need to run a command that uses quotation marks, you must properly escape the quotations. The way you escape the quotations depends on whether you're using Bash or PowerShell.
In a Bash shell, use backslashes \
or double the the quotation marks:
*nix shell command
bolt command run "Get-WMIObject Win32_Service -Filter ""Name like '%mon'""" -t localhost
In a PowerShell shell, use a combination of backslashes \
and doubling of
quotation marks. The example below uses two double quotation marks to quote the
value being passed to Filter
, however the example also uses a backslash so
that Bolt's underlying Ruby argument parser accepts the command.
PowerShell cmdlet
Invoke-BoltCommand -Command "Get-WMIObject Win32_Service -Filter \""Name like '%mon'\""" -Targets localhost
Reading a command from a file is useful when you need to run a script on a target
that does not permit file uploads. To read a command from a file, pass an @
symbol,
followed by the relative path to the file.
*nix shell command
bolt command run @configure.sh --targets servers
PowerShell cmdlet
Invoke-BoltCommand -Command '@configure.ps1' -Targets servers
Note: In PowerShell, always wrap the file name in single quotes.
To read a command from standard input (stdin), pipe the results from another
command to Bolt and pass a single dash (-
) as the command.
*nix shell command
cat command.sh | bolt command run - --targets servers
Reading from stdin is not supported by the PowerShell module.
The most common way to specify targets on the command line is with the
targets
option. This option accepts a comma-separated list of targets.
*nix shell command
bolt command run 'pwd' --targets bolt1.example.org,bolt2.example.org
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets bolt1.example.org,bolt2.example.org
If you have an inventory file, you can list targets and groups of targets by name instead of using the target's Universal Resource Identifier (URI).
*nix shell command
bolt command run 'pwd' --targets servers,databases
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets servers,databases
Bolt supports extended glob matching for targets. This is helpful when you have
several targets that you want to run a comand on that have similar names. For
example, to run a command on all targets that start with the word bolt
:
*nix shell command
bolt command run 'pwd' --targets 'bolt*'
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets 'bolt*'
Bolt supports globs using the following metacharacters:
Metacharacter |
Description |
---|---|
* |
Matches any number of characters. For example, target* matches any target that begins with the word target . |
? |
Matches any single character. For example, target? matches any target that begins with the word target and is followed by a single character. |
[SET] |
Matches any single character in the set. For example, target[1-3] matches target1 , target2 , and target3 . |
[^SET] |
Matches any single character that is not in the set. For example, target[^3] matches target1 and target2 , but not target3 . |
{a,b} |
Matches all patterns in the set. For example {target,node}1 matches target1 and node1 . |
\ |
Escapes the next metacharacter. |
Extended glob matching is only supported when specifying targets from the command-line interface. Plans do not support extended glob matching.
To read a file of targets, pass an @
symbol, followed by the relative path to
the file, to the targets
option.
*nix shell command
bolt command run 'pwd' --targets '@targets.txt'
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets '@targets.txt'
Note: In PowerShell, always wrap the file name in single quotes.
To read a list of targets from stdin, pipe the results from another command to
Bolt and pass a single dash (-
) to the targets
option.
*nix shell command
cat targets.txt | bolt command run 'pwd' --targets -
Reading from stdin is not supported by the PowerShell module.
After every execution, Bolt writes information about the result of that run to a
.rerun.json
file inside the Bolt project directory. You can use the
.rerun.json
file together with the rerun
option to specify targets for
future commands. The rerun
option accepts one of three values:
success
: The list of targets the command succeeded on.failure
: The list of targets the command failed on.all
: All of the targets the command ran on.
For example, if you need to run a command that is dependent on the success of
the previous command, you can target the successful targets with the success
value.
*nix shell command
bolt task run restart_server --targets servers --rerun success
PowerShell cmdlet
Invoke-BoltTask -Name restart_server -Targets servers -Rerun success
If you want to preserve the results of a specific Bolt run and run multiple
rerun
commands against it, you can disable the .rerun.json
file.
*nix shell command
Use the --no-save-rerun
option to disable saving the rerun file:
bolt task run restart_server --targets server --rerun success --no-save-rerun
PowerShell cmdlet
Use the -SaveRerun
argument with a value of $false
to disable saving the
rerun file:
Invoke-BoltTask -Name restart_server -Targets servers -Rerun success -SaveRerun:$false
To establish connections with remote targets, Bolt needs to provide credentials to the target. You can provide credentials at the command line or in an inventory file, and the credentials you provide might vary based on the operating system the target is running.
Whether a target is running a Unix-like operating system or Windows, the
simplest way to specify credentials is to pass the user
and password
to the Bolt command:
*nix shell command
bolt command run 'pwd' --targets servers --user bolt --password puppet
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets servers -User bolt -Password puppet
If you'd prefer to have Bolt securely prompt for a password, so that it does not
appear in a process listing or on the console, use the password-prompt
option
instead:
*nix shell command
bolt command run 'pwd' --targets servers --user bolt --password-prompt
PowerShell cmdlet
Invoke-BoltCommand -Command 'pwd' -Targets servers -User bolt -PasswordPrompt
Bolt uses a specific transport to establish a connection with a target. By
default, Bolt connects to targets using the ssh
transport. You can use one of
the methods below to set a different transport from the command line, or you can
configure transports in your inventory file.
You can specify the transport used to connect to a specific target by setting it as the protocol in the target's URI:
*nix shell command
bolt command run 'Get-Location' --targets winrm://windows.example.org
PowerShell cmdlet
Invoke-BoltCommand -Command 'Get-Location' -Targets winrm://windows.example.org
You can also use the transport
command-line option:
*nix shell command
bolt command run 'Get-Location' --targets windows.example.org --transport winrm
PowerShell cmdlet
Invoke-BoltCommand -Command 'Get-Location' -Targets windows.example.org -Transport winrm
📖 Related information
🧪 This feature is experimental and is subject to change.
Bolt can stream output from running commands and scripts on a target, allowing you to see what is happening on a target as an action runs.
To enable streaming from the command line, you can specify the stream
command-line
option:
*nix shell command
bolt command run whoami --targets servers --stream
PowerShell cmdlet
Invoke-BoltCommand -Command whoami -Targets servers -Stream
To enable streaming for all commands and scripts, add the stream
option to
a bolt-project.yaml
or bolt-defaults.yaml
configuration file:
---
name: myproject
stream: true
When streaming is enabled, Bolt prints the output to the console in the order it
receives it. Each line of the output includes the name of the target that
returned the output and whether it was printed to standard output (out
) or
standard error (err
).
$ bolt command run 'echo stdout && echo stderr 1>&2' -t localhost --stream
Started on localhost...
[localhost] out: stdout
[localhost] err: stderr
Finished on localhost:
stdout
stderr
Successful on 1 target: localhost
Ran on 1 target in 0.01 sec
Once an action finishes running, Bolt prints all of the output from a target
under the target's name. If you do not want to see the output a second time, you
can specify the no-verbose
command-line option when running a command or
script. This command-line option does not have a corresponding configuration
option.
*nix shell command
bolt command run whoami --targets servers --stream --no-verbose
PowerShell cmdlet
Invoke-BoltCommand -Command whoami -Targets servers -Stream -Verbose:$false
When you specify no-verbose
, the output from the target is only printed once.
$ bolt command run 'echo stdout && echo stderr 1>&2' -t localhost --stream --no-verbose
Started on localhost...
[localhost] out: stdout
[localhost] err: stderr
Finished on localhost:
Successful on 1 target: localhost
Ran on 1 target in 0.01 sec
When you run a script on a target Bolt copies the script from your Bolt controller to a temporary directory on the target, runs the script, and then deletes the script from the temporary directory.
You can run scripts in any language, as long as the appropriate interpreter is installed on the system. This includes any scripting language the system can run.
To run a script, provide the path to the script on the Bolt controller and a list of targets to run the script on.
*nix shell command
bolt script run ./scripts/configure.sh --targets servers
PowerShell cmdlet
Invoke-BoltScript -Script ./scripts/configure.ps1 -Targets servers
You can also run scripts that are part of a project or module. Scripts that are
part of a project or module are saved in the scripts/
directory. To run the
script, specify a Puppet file path with the form <MODULE OR PROJECT NAME>/scripts/<FILE NAME>
:
*nix shell command
bolt script run my_module/scripts/configure.sh --targets servers
PowerShell cmdlet
Invoke-BoltScript -Script my_module/scripts/configure.ps1 -Targets servers
Argument values are passed literally and are not interpolated by the shell on the target.
*nix shell command
To pass arguments to a script, specify them after the command:
bolt script run ./scripts/configure.sh --targets servers arg1 arg2
PowerShell cmdlet
To pass arguments to a script, specify them after the command:
Invoke-BoltScript -Script ./scripts/configure.sh -Targets servers arg1 arg2
You can also use the -Arguments
parameter and provide a comma-separated
list of arguments:
Invoke-BoltScript -Script ./scripts/configure.sh -Targets servers -Arguments arg1,arg2
🔩 Tip: If an argument contains spaces or special characters, wrap them in single quotes.
Depending on a target's operating system, there are additional requirements for running scripts:
-
On Unix-like targets, your scripts must include a shebang line specifying the interpreter. For example, a Bash script should provide the path to the Bash interpreter:
#!/bin/bash echo hello
-
For Windows targets, you might need to enable file extensions. By default, Windows targets support the extensions
.ps1
,.rb
, and.pp
. To add additional file extensions, add them to thewinrm
configuration section of your inventory file:# inventory.yaml config: winrm: extensions: - .py - .pl
Tasks are single actions that you can execute on a target. They are similar to scripts, but have metadata, accept structured input, and return structured output. You can write tasks that are specific to your project or download modules from the Puppet Forge that include tasks.
To run a task, provide the name of the task and a list of targets to run the task on.
*nix shell command
bolt task run facts --targets servers
PowerShell cmdlet
Invoke-BoltTask -Name facts -Targets servers
If a task accepts parameters, you can pass them to Bolt as part of the command.
*nix shell command
To pass parameters to a task, add parameter declarations of the form
parameter=value
to the command:
bolt task run package action=status name=apache2 --targets servers
PowerShell cmdlet
To pass parameters to a task, add an object with parameter declarations to the command:
Invoke-BoltTask -Name package -Targets servers -Params @{action='status';name='apache2'}
📖 Related information
Plans are sets of tasks and commands that can be combined with other logic. They allow you to do complex operations, such as running multiple tasks with one command, computing values for the input for a task, or running certain tasks based on the results of another task. Similar to tasks, you can write plans that are specific to your project or download modules from the Puppet Forge that include plans.
To run a plan, provide the name of the plan.
*nix shell command
bolt plan run myplan
PowerShell cmdlet
Invoke-BoltPlan -Name myplan
If a plan accepts parameters, you can pass them to Bolt as part of the command.
*nix shell command
To pass parameters to a plan, add parameter declarations of the form
parameter=value
to the command:
bolt plan run reboot targets=servers
PowerShell cmdlet
To pass parameters to a task, add an object with parameter declarations to the command:
Invoke-BoltTask -Name reboot -Params @{targets='servers'}
If a plan accepts a targets
parameter with the type TargetSpec
, you can
use the targets
command-line option to provide a value to the parameter.
*nix shell command
bolt task run reboot --targets servers
PowerShell cmdlet
Invoke-BoltPlan -Name reboot -Targets servers
📖 Related information
Bolt can copy files and directories from your Bolt controller to targets. To
upload a file or directory, provide the source
path on your Bolt controller, the
destination
path on the target that it should be copied to, and a
list of targets.
Both the source
and destination
accept absolute and relative paths. If you
provide a relative path as the destination
, Bolt will copy the file relative
to the current working directory on the target. Typically, the current working
directory for the target is the log-in user's home directory.
*nix shell command
bolt file upload /path/to/source /path/to/destination --targets servers
PowerShell cmdlet
Send-BoltFile -Source /path/to/source -Destination /path/to/destination -Targets servers
Bolt can copy files and directories from targets to a destination
directory on your Bolt controller. To download a file or directory, provide the
source
path on the target, the path to the destination
directory on
the Bolt controller, and a list of targets.
Both the source
and destination
accept absolute and relative paths. If you
provide a relative path as the source
, Bolt will copy the file relative to the
current working directory on the target. Typically, the current working
directory for the target is the log-in user's home directory.
*nix shell command
bolt file download /path/to/source /path/to/destination --targets servers
PowerShell cmdlet
Receive-BoltFile -Source /path/to/source -Destination /path/to/destination -Targets servers
The destination
on the Bolt controller is a path to a directory that the downloaded
file or directory is copied to. If the destination
directory does not exist,
Bolt will create it for you.
Bolt saves each file or directory it downloads to a subdirectory of the
destination
directory that matches the URL-encoded name of the target it was
downloaded from. The target directory names are URL-encoded to ensure that they
are valid directory names.
For example, the following command downloads the SSH daemon configuration file from
two targets, linux
and ssh://example.com
, saving it to the destination
directory sshd_config
:
*nix shell command
bolt file download /etc/ssh/sshd_config sshd_config --targets linux,ssh://example.com
PowerShell cmdlet
Receive-BoltFile -Source /etc/ssh/sshd_config -Destination sshd_config -Targets linux,ssh://example.com
After running this command from the root of your project directory, your project directory structure would look similar to this:
.
├── bolt-project.yaml
├── inventory.yaml
└── sshd_config/
├── linux/
│ └── sshd_config
└── ssh%3A%2F%2Fexample.com/
└── sshd_config
🔩 Tip: To avoid creating directories with special characters, give your targets a simple, human-readable name.
You can directly apply Puppet code from a file containing Puppet code (known as a manifest) to your targets. To apply Puppet manifest code to a target, provide the path to the manifest file and a list of targets.
The Puppet Agent package needs to be installed on the target for the manifest code to be run. When you apply Puppet manifest code, Bolt ensures that the Puppet Agent package is installed on the target.
*nix shell command
bolt apply manifests/servers.pp --targets servers
PowerShell cmdlet
Invoke-BoltApply -Manifest manifests/servers.pp -Targets servers
You can also apply Puppet code directly to your targets, without the need
for writing it to a file first. To apply Puppet code directly to a target,
use the execute
command-line option.
*nix shell command
bolt apply --execute "file { '/etc/puppetlabs': ensure => present }" --targets servers
PowerShell cmdlet
Invoke-BoltApply -Execute "file { '/etc/puppetlabs': ensure => present}" -Targets servers
📖 Related information