bolt 0.0.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e17f05abe379ebb5107bad53ab43677776bba590
-  data.tar.gz: 7150db2fe239c6b61c9af86939e2ba69b7174c5a
+  metadata.gz: a2f060b4f462b01b52b2124b466b31afb8f5d4a5
+  data.tar.gz: 1d3384d30e628a6ec5ccac3b8ed906119d78ae16
 SHA512:
-  metadata.gz: 27eaa83fd43226e37f01a91261ef9734d5e298d3ba026091bf09f7b421f64542003bfe52252ff7ebd6f0b3ca7edd1f8b9b5e1c8da4ce4db6d07839a73b47f32f
-  data.tar.gz: 80a3b00ed01491ddf7641a5ab4af4a1e27591c61c198ebbec7c85061f7815166bf335bd1504863f0dcebc72e7910d87cf93f26bf260288fc0c42675e36b8bc13
+  metadata.gz: 29385451ff01d103ea9f916c4e4241ce740401a45624d7644d205e5ee0064fa5f035702d13d0b542e723b2de25d6662bd69fb9182eb8300f72ccdf2427169cf3
+  data.tar.gz: e2504ed3ab58c8dd2828b715df0ffd0bfabfcaf2e3bf2bb9679cd6e0794c03a33def73dbc439968d4cfe8c18491df438f1ffd097371d0eede7db2a16d758f44f

data/.gitignore

@@ -0,0 +1,33 @@
+*.gem
+*.rbc
+/.config
+/.idea
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+Gemfile.lock
+Gemfile.local
+.ruby-version
+.ruby-gemset
+
+.rvmrc
+
+.vagrant/
+.byebug_history

data/.gitmodules

@@ -0,0 +1,12 @@
+[submodule "vendored/puppet"]
+	path = vendored/puppet
+	url = https://github.com/puppetlabs/puppet
+	branch = feature_puppet-tasks
+[submodule "vendored/hiera"]
+	path = vendored/hiera
+	url = https://github.com/puppetlabs/hiera
+	branch = 3.4.x
+[submodule "vendored/facter"]
+	path = vendored/facter
+	url = https://github.com/puppetlabs/facter
+	branch = 2.x

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/.rubocop.yml

@@ -0,0 +1,61 @@
+AllCops:
+  TargetRubyVersion: 2.0
+  Exclude:
+    - 'vendor/**/*'
+    - 'vendored/**/*'
+
+# Checks for if and unless statements that would fit on one line if written as a
+# modifier if/unless.
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Layout/IndentHeredoc:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+
+# Disable nearly all Metrics checks. These seem better off left to judgement.
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,18 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+- 2.4
+- 2.0
+before_script:
+- cat Gemfile.lock
+script:
+- bundle exec rake unit rubocop
+notifications:
+  email: false
+  hipchat:
+    rooms:
+      secure: g7ViGa4EwzqVmbiu2RXk6BXJi3nfLIAMwCojJkD7d2OZ6hmButPP15jB4KaZ/3WTDKNO0elo1wcIdVCJBnZpELPAC32xdcQ43Ft6W5NVDaJwxO4xl836OLboIStSd+7W8raVcarCh5UTDvZbm/9B13o6uaL+GaP2Lpilr2GKZRAABw2hjC58vUBFMZvUN6q7oQ96up1NG6vpsZ3uCitPEvVemGn4kqC9dkLOWGZGRx21fTyL10ttQ5R21kQsp9efdlxyHqU3m96CNItw2yDHOKH3Z6FUtFwKyD+xzqOOAESt5ZgtT/g3XJK8koW2oKALSXwq+9eCfAisHQpotRciZY4pGoalVu3Zp000w26dJm0kDBdAmJ7LWVL3QK/qBxw00S+ODh1Du2WKLm+zAFYZ1O79LlnKQeDeqvL/Z+It8kMJrA/JUoQuyRrMouy5NAzjlGzZlC9kr2HUYzK2eBcxHfF8gJN0bnzalLnsR36RBgyDtLyuuIKouXo5GUkD/wDL+WbSuwejvWTDUxBATby5xq/VNwvgGJnXrAgs2HOR+k+V/dBeYjW5Ow4eqpGsnDT2EN4o6kmJDRubAMu6NIkJus5WKdyl/Q6BCvt7Gathzz1vUvhwhCt0elrkpeXYrq/g+MIHuLGl3IRbjTOy9gpcgbjRapRhwp/AzXY2EDqoGJM=
+    template:
+      - '<a href="https://github.com/%{repository_slug}">%{repository_name}</a>#<a href="%{build_url}">%{build_number}</a> (<a href="%{compare_url}">%{branch} - %{commit} : %{author}</a>): %{message}'
+    format: html

data/Gemfile

@@ -0,0 +1,9 @@
+source ENV['GEM_SOURCE'] || 'https://rubygems.org'
+
+gemspec
+
+gem "rubocop", require: false
+
+if File.exist? "Gemfile.local"
+  eval_gemfile "Gemfile.local"
+end

data/INSTALL.md

@@ -0,0 +1,70 @@
+# Installation
+
+To use Bolt, you'll need to install:
+
+* Ruby 2.0 or greater
+* gcc and related dependencies (except on Windows)
+* Bolt gem
+
+## Native Extensions
+
+Bolt is written entirely in Ruby, but it depends on gems containing native
+extensions. In order to install bolt on a supported platform, you will need a
+gcc compiler and related dependencies (except for Windows).
+
+### CentOS 7/Redhat 7
+
+    yum install -y make gcc ruby-devel
+
+### Fedora 25
+
+    dnf install -y make gcc redhat-rpm-config ruby-devel rubygem-rdoc
+
+### Debian 9/Ubuntu 16.04
+
+    apt-get install -y make gcc ruby-dev
+
+### OSX
+
+Either install XCode or the Command Line Tools. The latter can be done from the command line:
+
+     xcode-select --install
+
+### Windows
+
+Install [Chocolatey](https://chocolatey.org/install), then install `ruby`. It isn't necessary
+to install `ruby.devkit`, as ffi already publishes precompiled gems for Windows x86 and x64.
+
+    choco install ruby
+    refreshenv
+
+## Installing Bolt
+
+Bolt can be installed 3 ways depending on your use case. The most common case is
+to install from [RubyGems](https://rubygems.org).
+
+    gem install bolt
+
+Since bolt is not public yet, you will need to install the gem from our internal
+mirror, and specify a version to ensure you get the latest version:
+
+    gem install bolt --source http://rubygems.delivery.puppetlabs.net
+
+Or add this to your Gemfile if you are using [Bundler](https://bundler.io), and
+specify your gem `source` as `http://rubygems.delivery.puppetlabs.net`
+
+    gem 'bolt'
+
+Or if running from source
+
+    git submodule update --init --recursive
+    bundle install --path .bundle
+    bundle exec bolt ...
+
+See `bolt --help` for more details.
+
+## Installing Puppet
+
+Bolt vendors a version of puppet that supports executing tasks and plans, so you do not need
+to install puppet. If you happen to already have puppet installed, then the vendored version
+will take precedence and will not conflict with the already installed version.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,372 @@
+# Bolt
+
+[![Travis Status](https://api.travis-ci.com/puppetlabs/bolt.svg?token=XsSSSxJhnBoKnL8JPVay&branch=master)](https://travis-ci.com/puppetlabs/bolt)
+[![Appveyor Status](https://ci.appveyor.com/api/projects/status/m7dhiwxk455mkw2d/branch/master?svg=true)](https://ci.appveyor.com/project/puppetlabs/bolt/branch/master)
+[![Gem Version](https://badge.fury.io/rb/bolt.svg)](https://badge.fury.io/rb/bolt)
+
+Bolt is a Ruby command-line tool for executing commands, scripts, and tasks on remote systems using SSH and WinRM.
+
+* Executes commands on remote *nix and Windows systems.
+* Distributes and execute scripts, such as Bash, PowerShell, Python.
+* Scales to more than 1000 concurrent connections.
+* Supports industry standard protocols (SSH/SCP, WinRM/PSRP) and authentication methods (password, publickey).
+
+## Supported platforms
+
+* Linux, OSX, Windows
+* Ruby 2.0+
+
+## Installation
+
+Install Bolt as a gem by running `gem install bolt`.
+
+See [INSTALL.md](./INSTALL.md) for other ways of installing Bolt and for how to build the native extensions that Bolt depends on.
+
+## Running `bolt` commands
+
+Bolt executes ad hoc commands, runs scripts, transfers files, and runs tasks or task plans on remote nodes from a controller node, such as your laptop or workstation.
+
+When you run `bolt` commands, you must specify the nodes that you want Bolt to execute commands on. You can also specify your username and password for nodes that require credentials.
+
+Bolt connects to remote nodes over SSH by default. To connect over WinRM, you must specify the WinRM protocol when you specify target nodes.
+
+### Specifying nodes
+
+You must specify the target nodes on which to execute `bolt` commands.
+
+For most `bolt` commands, specify the target nodes with the `--nodes` flag when you run the command. Multiple nodes should be comma-separated, such as `--nodes neptune,saturn,mars`. When targeting WinRM machines, you must specify the WinRM protocol in the nodes string. For example, `--nodes winrm://mywindowsnode.mydomain`
+
+The `bolt run plan` command does not accept the `--nodes` flag. For plans, specify nodes as a list within the task plan itself or specify them as regular parameters, like `nodes=neptune`.
+
+### Specifying connection credentials
+
+If you're running `bolt` commands targeting nodes that require a username and password, you must pass those credentials as options on the command line.
+
+Bolt connects to remote nodes with either SSH or WinRM. You can manage SSH connections with an SSH configuration file (`~/.ssh/config`) on the controller node or specify the username and password on the command line. WinRM connections always require you to pass the username and password with the `bolt` command.
+
+For example, this command targets a WinRM node:
+
+```
+bolt command run 'gpupdate /force' --nodes winrm://pluto --user Administrator --password <password>
+```
+
+## Running arbitrary commands
+
+Bolt can execute arbitrary commands on remote nodes. Specify the command you want to run and what nodes to run the command on.
+
+Specify nodes with node flag, `--nodes` or `-n`. When executing against WinRM nodes, specify the WinRM protocol in the nodes string.
+
+    bolt command run <COMMAND> --nodes <NODE>
+
+    bolt command run <COMMAND> --nodes winrm://mywindowsnode.mydomain --user <USERNAME> --password <PASSWORD>
+
+If the command contains spaces or shell special characters, then you must single quote the command:
+
+    bolt command run '<COMMAND> <ARG1> ... <ARGN>' --nodes <NODE>
+
+## Running scripts
+
+Bolt can copy a script from the local system to the remote system, and then execute it on the remote system.
+
+You can write the script in any language (such as Bash, PowerShell, or Python), providing the appropriate interpreter is installed on the remote system. You must specify the interpreter with a shebang line to execute the script on remote *nix systems.
+
+For example, for a script written in bash, indicate the bash interpreter with a shebang line:
+
+```
+#!/bin/bash
+
+echo hello
+```
+
+To run the script, specify the path to the script and what nodes to run it on. When running a script on WinRM nodes, specify the WinRM protocol in the nodes string.
+
+```
+bolt script run <PATH/TO/SCRIPT> --nodes <NODE>
+```
+
+```
+bolt script run <PATH/TO/SCRIPT> --nodes winrm://<NODE> --user <USERNAME> --password <PASSWORD>
+```
+
+On *nix, Bolt ensures that the script is executable on the remote system before executing it. On remote Windows systems, Bolt currently supports only PowerShell scripts.
+
+## Copying files
+
+Bolt can transfer files from the controller node to specified target nodes.
+
+To transfer a file, run `bolt file upload`, specifying the local path to the file and the destination location on the target node: `bolt file upload <SOURCE> <DESTINATION>`
+
+For example:
+
+```
+bolt file upload my_file.txt /tmp/remote_file.txt -n node1,node2
+```
+
+## Running tasks
+
+Tasks are similar to scripts, except that tasks must receive input in a specific way. Tasks are also distributed in Puppet modules, so you can write, publish, and download tasks for common operations.
+
+To execute a task, run `bolt task run`, specifying:
+
+* The full name of the task, formatted as `<MODULE::TASK>`, or as `<MODULE>` for `init` tasks.
+* Any task parameters, as `parameter=value`.
+* The nodes to run the task on and the protocol, if WinRM, with the `--nodes` flag.
+* The module path that contains the module containing the task, with the `--modules` flag.
+* If required, the username and password to connect to the node, with the `--username` and `--password` flags.
+
+
+For example, to run the sql task from the mysql module on the `neptune` node:
+
+```
+bolt task run mysql::sql database=mydatabase sql="SHOW TABLES" --nodes neptune --modules ~/modules
+```
+
+To run an `init` task, call the task by the module name only, and set the task parameters. For example, to run the status action from the package module:
+
+```
+bolt run package action=status package=vim --nodes neptune --modules ~/modules
+```
+
+## Running plans
+
+Plans allow you to string several tasks together, and can include additional logic to trigger specific tasks.
+
+To execute a plan, run `bolt plan run`, specifying:
+
+* The full name of the plan, formatted as `<MODULE>::<PLAN>`.
+* Any plan parameters, as `parameter=value`.
+* The nodes to run the plan on and the protocol, if WinRM, as parameters to the plan: `parameters=value`. The `run plan` command ignores the `--nodes` flag.
+* The module path that contains the plan module, with the `--modules` flag.
+* If required, the username and password to connect to the node, with the `--username` and `--password` flags.
+
+For example, if  a plan defined in `mymodule/plans/myplan.pp` accepts a `load_balancer` parameter to specify a node on which to run tasks or functions in the plan, run:
+
+```
+bolt plan run mymodule::myplan --modules ./PATH/TO/MODULES load_balancer=lb.myorg.com​
+```
+
+### Specifying the module path
+
+When executing tasks or plans, you must specify the `--modules` option as the directory containing the module. Specify this option in the format `--modules /path/to/modules`, should correspond to a directory structure:
+
+```
+/path/to/modules/
+  mysql/
+    tasks/
+      sql
+```
+
+### Specifying parameters
+
+Tasks can receive input as either environment variables or a JSON hash on standard input. By default, Bolt submits parameters as both environment variables and stdin.
+
+When executing the task, specify the parameter value on the command line in the format `parameter=value`. Pass multiple parameters as a space-separated list.
+
+For example, to run mysql tasks against a database called 'mydatabase', specify the database parameter as `database=mydatabase`.
+
+When you run a command with this parameter, Bolt sets the task's `database` value to mydatabase before it executes the task. It also submits the parameters as JSON to stdin:
+
+```json
+{
+  "database":"mydatabase"
+}
+```
+
+Alternatively, you can specify parameters as either a JSON blob or a parameter file with the `--params` flag.
+
+To specify parameters as a JSON blob, use the parameters flag: `--params '{"database": "mydatabase"}'`
+
+To set parameters in a file, create a file called `params.json` and specify parameters there in JSON format.
+
+For example, in your `params.json` file, specify:
+
+```json
+{
+  "database":"mydatabase"
+}
+```
+
+Then specify that file on the command line with the parameters flag: `--params @params.json`
+
+### Configuring Puppet Orchestrator for Bolt
+
+Bolt can use the Puppet orchestrator to target nodes using the `pcp` protocol when running on linux.
+
+1. Configure `~/.puppetlabs/client-tools/orchestrator.conf` to include
+   service-url and cacert options to connect to you puppet master.
+1. Store a PE RBAC token in `~/.puppetlabs/token`.
+1. Install the bolt helper task `tasks/init` by installing this repository into
+   the production environment on your puppet master. Without this task the
+   exec, script and file commands will not work in Bolt.
+1. To run tasks over orchestrator the tasks must be installed both on the bolt
+   node and into the production environment on the master
+
+## Usage examples
+
+### Get help
+
+    $ bolt --help
+    Usage: bolt <subcommand> <action> [options]
+    ...
+
+### Run a command over SSH
+
+    $ bolt command run 'ssh -V' --nodes neptune
+    neptune:
+
+    OpenSSH_5.3p1, OpenSSL 1.0.1e-fips 11 Feb 2013
+
+    Ran on 1 node in 0.27 seconds
+
+### Run a command over SSH against multiple hosts
+
+    $ bolt command run 'ssh -V' --nodes neptune,mars
+    neptune:
+
+    OpenSSH_5.3p1, OpenSSL 1.0.1e-fips 11 Feb 2013
+
+    mars:
+
+    OpenSSH_6.6.1p1, OpenSSL 1.0.1e-fips 11 Feb 2013
+
+    Ran on 2 nodes in 0.27 seconds
+
+### Run a command over WinRM
+
+    $ bolt command run 'gpupdate /force' --nodes winrm://pluto --user Administrator --password <password>
+    pluto:
+
+    Updating policy...
+
+    Computer Policy update has completed successfully.
+
+    User Policy update has completed successfully.
+
+    Ran on 1 node in 11.21 seconds
+
+### Run a command over WinRM against multiple hosts
+
+    $ bolt command run '(Get-CimInstance Win32_OperatingSystem).version' --nodes winrm://pluto,winrm://mercury --user Administrator --password <password>
+    pluto:
+
+    6.3.9600
+
+    mercury:
+
+    10.0.14393
+
+    Ran on 2 nodes in 6.03 seconds
+
+### Run a bash script
+
+    $ bolt script run ./install-puppet-agent.sh --nodes neptune
+    neptune: Installed puppet-agent 5.1.0
+
+### Run a PowerShell script
+
+    $ bolt script run Get-WUServiceManager.ps1 --nodes winrm://pluto --user Administrator --password <password>
+    pluto:
+
+    Name                  : Windows Server Update Service
+    ContentValidationCert : {}
+    ExpirationDate        : 6/18/5254 9:21:00 PM
+    IsManaged             : True
+    IsRegisteredWithAU    : True
+    IssueDate             : 1/1/2003 12:00:00 AM
+    OffersWindowsUpdates  : True
+    RedirectUrls          : System.__ComObject
+    ServiceID             : 3da21691-e39d-4da6-8a4b-b43877bcb1b7
+    IsScanPackageService  : False
+    CanRegisterWithAU     : True
+    ServiceUrl            :
+    SetupPrefix           :
+    IsDefaultAUService    : True
+
+### Run the `sql` task from the `mysql` module
+
+    $ bolt task run mysql::sql database=mydatabase sql="SHOW TABLES" --nodes neptune --modules ~/modules
+
+### Run the special `init` task from the `service` module
+
+    $ bolt task run service name=apache --nodes neptune --modules ~/modules
+    neptune:
+
+    { status: 'running', enabled: true }
+
+### Upload a file
+
+    $ bolt file upload /local/path /remote/path --nodes neptune
+    neptune:
+
+    Uploaded file '/local/path' to 'neptune:/remote/path'
+
+### Run the `deploy` plan from the `webserver` module
+
+    $ bolt plan run webserver::deploy version=1.2 --modules ~/modules
+
+    Deployed app version 1.2.
+
+Note the `--nodes` option is not used with plans, as they can contain more complex logic about where code is run. A plan can use normal parameters to accept nodes when applicable, as in the next example.
+
+### Run the `single_task` plan from the `sample` module in this repo
+
+    $ bolt plan run sample::single_task nodes=neptune --modules spec/fixtures/modules
+    neptune got passed the message: hi there
+
+## Kudos
+
+Thank you to [Marcin Bunsch](https://github.com/marcinbunsch) for allowing Puppet to use the `bolt` gem name.
+
+## Contributing
+
+Please submit new issues on the GitHub issue tracker: https://github.com/puppetlabs/bolt/issues
+
+Pull requests are also welcome on GitHub: https://github.com/puppetlabs/bolt
+
+As with other open-source projects managed by Puppet, Inc we require contributors to digitally sign the Contributor 
+License Agreement before we can accept your pull request: https://cla.puppet.com
+
+Internally, Puppet uses JIRA for tracking work, so nontrivial bugs or enhancement requests may migrate to JIRA tickets 
+in the "BOLT" project: https://tickets.puppetlabs.com/browse/BOLT/ 
+
+## Testing
+
+Some tests require a Windows or Linux VM. Execute `vagrant up` to bring these up with the Vagrantfile included with the `bolt` gem. Any tests that require this are tagged with `:vagrant` in rspec.
+
+To run all tests, run:
+
+    $ bundle exec rake test
+
+To exclude tests that rely on Vagrant, run:
+
+    $ bundle exec rake unit
+
+## FAQ
+
+### Bolt requires Ruby >= 2.0
+
+Trying to install Bolt on Ruby 1.9 fails. You must use Ruby 2.0 or greater.
+
+### Bolt fails to install
+
+If you do not have the native extensions Bolt requires, you might get an error like:
+
+```
+ERROR:  Error installing bolt:
+    ERROR: Failed to build gem native extension.
+```
+
+See [Native Extensions](./INSTALL.md#native-extensions) for installation instructions.
+
+### Bolt raises the error `Puppet must be installed to execute tasks`
+
+When using the bolt gem from source, you may receive the error `Puppet must be installed to execute tasks` when trying to run tasks or plans. See [INSTALL.md](./INSTALL.md) on how to install Bolt from source.
+
+### Bolt user and password cannot be specified when running plans
+
+In order to execute a plan, Bolt must be able to SSH (typically using ssh-agent) to each node. For Windows hosts requiring WinRM, plan execution will fail. See [BOLT-85](https://tickets.puppet.com/browse/BOLT-85).
+
+## License
+
+The gem is available as open source under the terms of the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+