ruby-terraform 0.65.0.pre.12 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aa09973516552eca1e86476c1a12da268f105a8a78d87ac4366c59e8051e5d4
-  data.tar.gz: ccfc2afc555c53f30fb61f429e33d9451102aba3d3a39b68e69ebb546406bc10
+  metadata.gz: 8e6f8748d4275fd6af4f13f53eb3440b10012bc05895b1f3e7bf1e4f29614720
+  data.tar.gz: 315faa89600f7f8d31b92b47e66dc500a71bd5ea5c92ab214195a37738f65237
 SHA512:
-  metadata.gz: ed32ad7e4f4b6f98a78cea339ddfc2464d11a892a9ad8d4402a9af7a7d2224bae3cd75384c1a85c210a12efecd40b22bd85b575031ecef390c6da637150756e9
-  data.tar.gz: 98304e9c66825275ee0891b244bbe5ee47c3073f0b2c845afbb8cd30bd1297e791ab8367e151ebaf9b2452c0490ad3b55e013416b92f49b6af0dcc305b6ff190
+  metadata.gz: a30d286d7565203a82a299f210df2c6293999b11b66e6547cf721610648621550552a50d95b6a54363cdbb7414e1f66f00628b3f3086149162deb5df9d6df77f
+  data.tar.gz: 2225cfc75f9233fd5017eee048913ce850c37f85d636f1057786a29c683088a5408c897b3a9845c13381613ac1b12b8b2045d7f69682a0af7081c7b225717f4c

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    ruby-terraform (0.65.0.pre.12)
-      immutable-struct (>= 2.4)
-      lino (>= 2.5)
+    ruby-terraform (1.0.0)
+      immutable-struct (~> 2.4)
+      lino (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.3.1)
+    activesupport (6.1.3.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -22,14 +22,18 @@ GEM
     concurrent-ruby (1.1.8)
     diff-lcs (1.4.4)
     docile (1.3.5)
-    excon (0.79.0)
+    excon (0.81.0)
     faker (2.17.0)
       i18n (>= 1.6, < 2)
-    faraday (1.3.0)
+    faraday (1.4.1)
+      faraday-excon (~> 1.1)
       faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.1)
       multipart-post (>= 1.2, < 3)
-      ruby2_keywords
+      ruby2_keywords (>= 0.0.4)
+    faraday-excon (1.1.0)
     faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.1.0)
     ffi (1.15.0)
     formatador (0.2.5)
     gem-release (2.2.1)
@@ -52,7 +56,7 @@ GEM
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
     immutable-struct (2.4.1)
-    lino (2.5.0)
+    lino (2.7.0)
       hamster (~> 3.0)
       open4 (~> 1.3)
     listen (3.5.1)
@@ -66,12 +70,12 @@ GEM
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    octokit (4.20.0)
+    octokit (4.21.0)
       faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
     parallel (1.20.1)
-    parser (3.0.1.0)
+    parser (3.0.1.1)
       ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
@@ -117,20 +121,20 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    rubocop (1.12.1)
+    rubocop (1.14.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.5.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.4.1)
-      parser (>= 2.7.1.5)
+    rubocop-ast (1.5.0)
+      parser (>= 3.0.1.1)
     rubocop-rake (0.5.1)
       rubocop
-    rubocop-rspec (2.2.0)
+    rubocop-rspec (2.3.0)
       rubocop (~> 1.0)
       rubocop-ast (>= 1.1.0)
     ruby-progressbar (1.11.0)
@@ -146,12 +150,13 @@ GEM
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.2)
+    simplecov_json_formatter (0.1.3)
     sshkey (2.0.0)
     thor (1.1.0)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.0.0)
+    yard (0.9.26)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -174,6 +179,7 @@ DEPENDENCIES
   rubocop-rspec (~> 2.2)
   ruby-terraform!
   simplecov (~> 0.21)
+  yard (~> 0.9)
 
 BUNDLED WITH
-   2.2.16
+   2.2.17

data/README.md

@@ -1,7 +1,7 @@
 # RubyTerraform
 
 A simple wrapper around the Terraform binary to allow execution from within
-a Ruby program or Rakefile.
+a Ruby program, RSpec test or Rakefile.
 
 
 ## Installation
@@ -23,468 +23,161 @@ Or install it yourself as:
 
 ## Usage
 
-RubyTerraform needs to know where the terraform binary is located before it
-can do anything. By default, RubyTerraform looks on the path however this can
-be configured with:
+To require `RubyTerraform`:
 
 ```ruby
-RubyTerraform.configure do |config|
-  config.binary = 'vendor/terraform/bin/terraform'
-end
-```
-
-In addition, each command that requires the terraform binary (all except
-`clean`) takes a `binary` keyword argument at initialisation that overrides the
-global configuration value.
-
-Currently, there is partial support for the following commands:
-* `RubyTerraform::Commands::Clean`: clean up all locally held terraform state
-  and modules.
-* `RubyTerraform::Commands::Init`: executes `terraform init`
-* `RubyTerraform::Commands::Get`: executes `terraform get`
-* `RubyTerraform::Commands::Plan`: executes `terraform plan`
-* `RubyTerraform::Commands::Apply`: executes `terraform apply`
-* `RubyTerraform::Commands::Show`: executes `terraform show`
-* `RubyTerraform::Commands::Destroy`: executes `terraform destroy`
-* `RubyTerraform::Commands::Output`: executes `terraform output`
-* `RubyTerraform::Commands::Refresh`: executes `terraform refresh`
-* `RubyTerraform::Commands::Import`: executes `terraform import`
-* `RubyTerraform::Commands::RemoteConfig`: executes `terraform remote config`
-* `RubyTerraform::Commands::Format`: executes `terraform fmt`
-* `RubyTerraform::Commands::Validate`: executes `terraform validate`
-* `RubyTerraform::Commands::Workspace`: executes `terraform workspace`
-
-### RubyTerraform::Commands::Clean
-
-The clean command can be called in the following ways:
-
-```ruby
-RubyTerraform.clean
-RubyTerraform.clean(directory: 'infra/.terraform')
-RubyTerraform::Commands::Clean.new(directory: 'infra/.terraform').execute
-RubyTerraform::Commands::Clean.new.execute(directory: 'infra/.terraform')
+require 'ruby-terraform'
 ```
 
-When called, it removes the contents of the .terraform directory in the
-working directory by default. If another directory is specified, it instead
-removes the specified directory.
-
-
-### RubyTerraform::Commands::Init
+### Supported versions and commands
 
-The init command will initialise a terraform environment. It can be called in
-the following ways:
-
-```ruby
-RubyTerraform.init
-RubyTerraform.init(from_module: 'some/module/path', path: 'infra/module')
-RubyTerraform::Commands::Init.new.execute
-RubyTerraform::Commands::Init.new.execute(
-    from_module: 'some/module/path',
-    path: 'infra/module')
-```
+`RubyTerraform` supports all commands and options up to Terraform 0.15, except
+`terraform console`, `terraform test` and `terraform version`.
 
-The init command supports the following options passed as keyword arguments:
-* `from_module`: the source module to use to initialise; required if `path` is
-  specified
-* `path`: the path to initialise.
-* `backend`: `true`/`false`, whether or not to configure the backend.
-* `get`: `true`/`false`, whether or not to get dependency modules.
-* `backend_config`: a map of backend specific configuration parameters.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-* `plugin_dir`: directory containing plugin binaries. Overrides all default;
-  search paths for plugins and prevents the automatic installation of plugins.
+### Getting started
 
+There are a couple of ways to call Terraform using `RubyTerraform`.
 
-### RubyTerraform::Commands::Get
+Firstly, the `RubyTerraform` module includes class methods for each of the
+supported Terraform commands. Each class method takes a parameter hash
+containing options to pass to Terraform.
 
-The get command will fetch any modules referenced in the provided terraform
-configuration directory. It can be called in the following ways:
-
-```ruby
-RubyTerraform.get(directory: 'infra/networking')
-RubyTerraform::Commands::Get.new.execute(directory: 'infra/networking')
-```
-
-The get command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `update`: whether or not already downloaded modules should be updated;
-  defaults to `false`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-
-
-### RubyTerraform::Commands::Plan
-
-The plan command will generate the execution plan in the provided
-configuration directory. It can be called in the following ways:
+For example, to save the plan of changes for a Terraform configuration located
+under `infra/network` to a file called `network.tfplan` whilst providing some
+vars:
 
 ```ruby
 RubyTerraform.plan(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-RubyTerraform::Commands::Plan.new.execute(
-  directory: 'infra/networking',
+  chdir: 'infra/network',
+  out: 'network.tfplan',
   vars: {
     region: 'eu-central'
-  })
+  },
+  var_file: 'defaults.tfvars'
+)
 ```
 
-The plan command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `target`: the address of a resource to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `targets`: and array of resource addresses to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `state`: the path to the state file in which to store state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `plan`: the name of the file in which to save the generated plan.
-* `input`: when `false`, will not ask for input for variables not directly set;
-  defaults to `true`.
-* `destroy`: when `true`, a plan will be generated to destroy all resources
-  managed by the given configuration and state; defaults to `false`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-
-
-### RubyTerraform::Commands::Apply
-
-The apply command applies terraform configuration in the provided terraform
-configuration directory. It can be called in the following ways:
+To apply the generated plan of changes:
 
 ```ruby
 RubyTerraform.apply(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-RubyTerraform::Commands::Apply.new.execute(
-  directory: 'infra/networking',
+  chdir: 'infra/network',
+  plan: 'network.tfplan',
   vars: {
     region: 'eu-central'
-  })
+  },
+  var_file: 'defaults.tfvars'
+)
 ```
 
-The apply command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `target`: the address of a resource to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `targets`: and array of resource addresses to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `state`: the path to the state file in which to store state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `backup`: the path to the backup file in which to store the state backup.
-* `input`: when `false`, will not ask for input for variables not directly set;
-  defaults to `true`.
-* `no_backup`: when `true`, no backup file will be written; defaults to `false`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-* `auto_approve`: if `true`, the command applys without prompting the user to
-  confirm the changes; defaults to `false`.
-
-
-### RubyTerraform::Commands::Show
-
-The show command produces human-readable output from a state file or a plan
-file. It can be called in the following ways:
-
-```ruby
-RubyTerraform.show(
-  path: 'infra/networking')
-RubyTerraform::Commands::Show.new.execute(
-  path: 'infra/networking')
-```
-
-The show command supports the following options passed as keyword arguments:
-* `path`: the path to a state or plan file; required.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-* `module_depth`: the depth of modules to show in the output; defaults to
-  showing all modules.
-* `json`: whether or not the output from the command should be in json format;
-  defaults to `false`.
-
-### RubyTerraform::Commands::Destroy
-
-The destroy command destroys all resources defined in the terraform
-configuration in the provided terraform configuration directory. It can be
-called in the following ways:
+...and to destroy the resulting resources:
 
 ```ruby
 RubyTerraform.destroy(
-  directory: 'infra/networking',
+  chdir: 'infra/network',
   vars: {
     region: 'eu-central'
-  })
-RubyTerraform::Commands::Destroy.new.execute(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-```
-
-The destroy command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `target`: the address of a resource to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `targets`: and array of resource addresses to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `state`: the path to the state file containing the current state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `force`: if `true`, the command destroys without prompting the user to confirm
-  the destruction; defaults to `false`.
-* `backup`: the path to the backup file in which to store the state backup.
-* `no_backup`: when `true`, no backup file will be written; defaults to `false`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-
-
-### RubyTerraform::Commands::Output
-
-The output command retrieves an output from a state file. It can be called in
-the following ways:
-
-```ruby
-RubyTerraform.output(name: 'vpc_id')
-RubyTerraform::Commands::Destroy.new.execute(name: 'vpc_id')
+  },
+  var_file: 'defaults.tfvars'
+)
 ```
 
-The output command supports the following options passed as keyword arguments:
-* `name`: the name of the output to retrieve; required.
-* `state`: the path to the state file containing the current state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-* `module`: the name of a module to retrieve output from.
-
-
-### RubyTerraform::Commands::Refresh
+Additionally, `RubyTerraform` allows command instances to be constructed and
+invoked separately. This is useful when you need to override global
+configuration on a command by command basis or when you need to pass a command
+around.
 
-The refresh command will reconcile state with resources found in the target
-environment. It can be called in the following ways:
+Using the command class approach, the equivalent plan invocation above can be
+achieved using:
 
 ```ruby
-RubyTerraform.refresh(
-  directory: 'infra/networking',
+command = RubyTerraform::Commands::Plan.new
+command.execute(
+  chdir: 'infra/network',
+  out: 'network.tfplan',
   vars: {
     region: 'eu-central'
-  })
-RubyTerraform::Commands::Refresh.new.execute(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
+  },
+  var_file: 'defaults.tfvars'
+)
 ```
 
-The refresh command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `target`: the address of a resource to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `targets`: and array of resource addresses to target; if both `target` and
-  `targets` are provided, all targets will be passed to terraform.
-* `state`: the path to the state file in which to store state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `input`: when `false`, will not ask for input for variables not directly set;
-  defaults to `true`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-
-
-### RubyTerraform::Commands::Import
-
-The import command imports existing infrastructure into your terraform state.
-It can be called in the following ways:
+See the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for
+more details on the supported commands.
 
-```ruby
-RubyTerraform.import(
-  directory: 'infra/networking',
-  address: 'a.resource.address',
-  id: 'a-resource-id',
-  vars: {
-    region: 'eu-central'
-  }))
-RubyTerraform::Commands::Import.new.execute(
-  directory: 'infra/networking',
-  address: 'a.resource.address',
-  id: 'a-resource-id',
-  vars: {
-    region: 'eu-central'
-  }))
-```
+### Parameters
 
-The import command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `address`: a valid resource address; required.
-* `id`: id of resource being imported; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `input`: when `false`, will not ask for input for variables not directly set;
-  defaults to `true`.
-* `state`: the path to the state file containing the current state; defaults to
-  terraform.tfstate in the working directory or the remote state if configured.
-* `no_backup`: when `true`, no backup file will be written; defaults to `false`.
-* `backup`: the path to the backup file in which to store the state backup.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-
-
-### RubyTerraform::Commands::RemoteConfig
-
-The remote config command configures storage of state using a remote backend. It
-has been deprecated and since removed from terraform but is retained in this
-library for backwards compatibility. It can be called in the following ways:
+The parameter hash passed to each command, whether via the class methods or the
+`#execute` method, supports all the options available on the corresponding 
+Terraform command. There are a few different types of options depending on what
+Terraform expects to receive:
+
+* `Boolean` options, accepting `true` or `false`, such as `:input` or `:lock`;
+* `String` options, accepting a single string value, such as `:state` or 
+  `:target`;
+* `Array<String>` options, accepting an array of strings, such as `:var_files`
+  `:targets`; and
+* `Hash<String,Object>` options, accepting a hash of key value pairs, where the
+  value might be complex, such as `:vars` and `:backend_config`.
+  
+For all options that allow multiple values, both a singular and a plural option
+key are supported. For example, to specify multiple var files during a plan:
 
 ```ruby
-RubyTerraform.remote_config(
-  backend: 's3',
-  backend_config: {
-    bucket: 'example-state-bucket',
-    key: 'infra/terraform.tfstate',
-    region: 'eu-west-2'
-  })
-RubyTerraform::Commands::RemoteConfig.new.execute(
-  backend: 's3',
-  backend_config: {
-    bucket: 'example-state-bucket',
-    key: 'infra/terraform.tfstate',
-    region: 'eu-west-2'
-  })
+RubyTerraform.plan(
+  chdir: 'infra/network',
+  out: 'network.tfplan',
+  var_file: 'defaults.tfvars',
+  var_files: %w[environment.tfvars secrets.tfvars]
+)
 ```
 
-The remote config command supports the following options passed as keyword
-arguments:
-* `backend`: the type of backend to use; required.
-* `backend_config`: a map of backend specific configuration parameters;
-  required.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
+In this case, all three var files are passed to Terraform.
 
-### RubyTerraform::Commands::Format
+Some options have aliases. For example, the `:out` option can also be provided
+as `:plan` for symmetry with other terraform commands. However, in such
+situations only one of the aliases should be used in the provided parameters
+hash.
 
-The format command formats the terraform directory specified. It can be called in the following ways:
+See the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for
+a more complete listing of available parameter options.
 
-```ruby
-RubyTerraform.format(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-RubyTerraform::Commands::Format.new.execute(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-```
+### Configuration
 
-The format command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration to be formatted; required.
-* `recursive`: Processes files in subdirectories;
-  defaults to `false`.
-* `list`: Don't list files whose formatting differs;
-  defaults to `false`.
-* `write`: Don't write to source files;
-  defaults to `false`.
-* `check`: Checks if the input is formatted, exit status will be 0 if all input is properly formatted and non zero otherwise;
-  defaults to `false`.
-* `diff`: Displays a diff of the formatting changes;
-  defaults to `false`.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-  
-### RubyTerraform::Commands::Validate
+`RubyTerraform` uses sensible defaults for all configuration options. However,
+there are a couple of ways to override the defaults when they are sufficient.
+
+#### Binary
 
-The validate command validates terraform configuration in the provided terraform
-configuration directory. It can be called in the following ways:
+By default, `RubyTerraform` looks for the Terraform binary on the system path.
+To globally configure a specific binary location:
 
 ```ruby
-RubyTerraform.validate(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
-RubyTerraform::Commands::Validate.new.execute(
-  directory: 'infra/networking',
-  vars: {
-    region: 'eu-central'
-  })
+RubyTerraform.configure do |config|
+  config.binary = 'vendor/terraform/bin/terraform'
+end
 ```
 
-The validate command supports the following options passed as keyword arguments:
-* `directory`: the directory containing terraform configuration; required.
-* `vars`: a map of vars to be passed in to the terraform configuration.
-* `var_file`: the path to a terraform var file; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `var_files`: an array of paths to terraform var files; if both `var_file` and
-  `var_files` are provided, all var files will be passed to terraform.
-* `no_color`: whether or not the output from the command should be in color;
-  defaults to `false`.
-* `check_variables`: if `true`, the command checks whether all variables have
-  been provided; defaults to `true`.
-* `json`: whether or not the output from the command should be in json format;
-  defaults to `false`.
-
-### RubyTerraform::Commands::Workspace
-
-The `workspace` command configures
-[Terraform Workspaces](https://www.terraform.io/docs/state/workspaces.html#using-workspaces).
-It can be used as follows:
+To configure the Terraform binary on a command by command basis, for example for
+the `Plan` command:
 
 ```ruby
-RubyTerraform.workspace(operation: 'list')
-RubyTerraform.workspace(operation: 'new', workspace: 'staging')
-RubyTerraform.workspace(operation: 'select', workspace: 'staging')
-RubyTerraform.workspace(operation: 'list')
-RubyTerraform.workspace(operation: 'select', workspace: 'default')
-RubyTerraform.workspace(operation: 'delete', workspace: 'staging')
+command = RubyTerraform::Commands::Plan.new(
+  binary: 'vendor/terraform/bin/terraform'
+)
+command.execute(
+  # ...
+)
 ```
 
-arguments:
-* `directory`: the directory containing terraform configuration, the default is
-  the current path.
-* `operation`: `list`, `select`, `new` or `delete`. default `list`.
-* `workspace`: Workspace name.
+#### Logging
 
+By default, `RubyTerraform` 's own log statements are logged to `$stdout` with
+level `info`.
 
-## Configuration
+To globally configure a custom logger:
 
-In addition to configuring the location of the terraform binary, RubyTerraform
-offers configuration of logging and standard streams. By default standard
-streams map to `$stdin`, `$stdout` and `$stderr` and all logging goes to
-`$stdout`.
-
-### Logging
-
-By default, RubyTerraform logs to `$stdout` with level `info`.
-
-To configure a custom logger:
-
-``` ruby
+```ruby
 require 'logger'
 
 logger = Logger.new($stdout)
@@ -495,13 +188,13 @@ RubyTerraform.configure do |config|
 end
 ```
 
-RubyTerraform supports logging to multiple different outputs at once,
+`RubyTerraform` supports logging to multiple different outputs at once,
 for example:
 
-``` ruby
+```ruby
 require 'logger'
 
-log_file = Logger::LogDevice.new('/foo/bar.log') # results in a file with sync true in the background
+log_file = Logger::LogDevice.new('/foo/bar.log')
 logger = Logger.new(RubyTerraform::MultiIO.new(STDOUT, log_file), level: :debug)
 
 RubyTerraform.configure do |config|
@@ -511,18 +204,37 @@ RubyTerraform.configure do |config|
   config.stderr = logger
 end
 ```
-> Creating the Logger with a file this way (using `Logger::LogDevice`), guarantees that the buffer content will be saved/written, as it sets **implicit flushing**.
+> Creating the Logger with a file this way (using `Logger::LogDevice`),
+> guarantees that the buffer content will be saved/written, as it sets
+> **implicit flushing**.
+
+Configured in this way, any logging performed by `RubyTerraform` will log to
+both `STDOUT` and the provided `log_file`.
 
-Configured in this way, any logging performed by RubyTerraform will log to both
-`STDOUT` and the provided `log_file`.
+To configure the logger on a command by command basis, for example for the 
+`Show` command:
 
-### Standard Streams
+```ruby
+require 'logger'
 
-By default, RubyTerraform uses streams `$stdin`, `$stdout` and `$stderr`.
+logger = Logger.new($stdout)
+logger.level = Logger::DEBUG
+
+command = RubyTerraform::Commands::Show.new(
+  logger: logger
+)
+command.execute(
+  # ...
+)
+```
+
+#### Standard streams
+
+By default, `RubyTerraform` uses streams `$stdin`, `$stdout` and `$stderr`.
 
 To configure custom output and error streams:
 
-``` ruby
+```ruby
 log_file = File.open('path/to/some/ruby_terraform.log', 'a')
 
 RubyTerraform.configure do |config|
@@ -535,7 +247,7 @@ In this way, both outputs will be redirected to `log_file`.
 
 Similarly, a custom input stream can be configured:
 
-``` ruby
+```ruby
 require 'stringio'
 
 input = StringIO.new("user\ninput\n")
@@ -548,6 +260,28 @@ end
 In this way, terraform can be driven by input from somewhere other than
 interactive input from the terminal.
 
+To configure the standard streams on a command by command basis, for example for
+the `Init` command:
+
+```ruby
+require 'logger'
+
+input = StringIO.new("user\ninput\n")
+log_file = File.open('path/to/some/ruby_terraform.log', 'a')
+
+command = RubyTerraform::Commands::Init.new(
+  stdin: input,
+  stdout: log_file,
+  stderr: log_file
+)
+command.execute(
+  # ...
+)
+```
+
+## Documentation
+
+* [API docs](https://infrablocks.github.io/ruby_terraform/index.html)
 
 ## Development