Run Bolt

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.

Run a command

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.

Run a quoted command

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

Read a command from a file

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.

Read a command from stdin

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.

Specify targets

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

Specify targets from an inventory file

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

Specify targets using glob matching

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.

Read targets from a file

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.

Read targets from stdin

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.

Specify targets from the previous command

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

Disable `.rerun.json`

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

Specify connection credentials

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

Specify a transport

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

Bolt transports reference

Stream output

🧪 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

Run a script

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

Pass arguments to a script

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.

Requirements for running a script

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 the winrm configuration section of your inventory file:
```
# inventory.yaml
config:
  winrm:
    extensions:
      - .py
      - .pl
```

Run a task

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

Pass parameters to a task

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

Run a plan

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

Pass parameters to a plan

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'}

Pass targets to a plan parameter

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

Upload a file or directory

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

Download a file or directory

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.

Apply Puppet code

Apply Puppet code from a file

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

Apply Puppet code from the command line

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

Applying Puppet code

Run Bolt

Run a command

Run a quoted command

Read a command from a file

Read a command from stdin

Specify targets

Specify targets from an inventory file

Specify targets using glob matching

Read targets from a file

Read targets from stdin

Specify targets from the previous command

Disable .rerun.json

Specify connection credentials

Specify a transport

Stream output

Run a script

Pass arguments to a script

Requirements for running a script

Run a task

Pass parameters to a task

Run a plan

Pass parameters to a plan

Pass targets to a plan parameter

Upload a file or directory

Download a file or directory

Apply Puppet code

Apply Puppet code from a file

Apply Puppet code from the command line

Disable `.rerun.json`