website: document env CLI

website/source/assets/stylesheets/_docs.scss

@@ -7,6 +7,7 @@ body.page-sub{
 }
 
 body.layout-backend-types,
+body.layout-commands-env,
 body.layout-commands-state,
 body.layout-alicloud,
 body.layout-archive,

website/source/docs/commands/env/delete.html.md

@@ -0,0 +1,39 @@
+---
+layout: "commands-env"
+page_title: "Command: env delete"
+sidebar_current: "docs-env-sub-delete"
+description: |-
+  The terraform env delete command is used to create a delete state environment.
+---
+
+# Command: env delete
+
+The `terraform env delete` command is used to delete an existing environment.
+
+## Usage
+
+Usage: `terraform env delete [NAME]`
+
+This command will delete the specified environment.
+
+To delete an environment, it must already exist, it must be empty, and
+it must not be your current environment. If the environment
+is not empty, Terraform will not allow you to delete it without the
+`-force` flag.
+
+If you delete a non-empty state (via force), then resources may become
+"dangling". These are resources that Terraform no longer manages since
+a state doesn't point to them, but still physically exist. This is sometimes
+preferred: you want Terraform to stop managing resources. Most of the time,
+however, this is not intended so Terraform protects you from doing this.
+
+The command-line flags are all optional. The list of available flags are:
+
+* `-force` - Delete the state even if non-empty. Defaults to false.
+
+## Example
+
+```
+$ terraform env delete example
+Deleted environment "example"!
+```

website/source/docs/commands/env/index.html.md

@@ -0,0 +1,21 @@
+---
+layout: "commands-env"
+page_title: "Command: env"
+sidebar_current: "docs-env-index"
+description: |-
+  The `terraform env` command is used to manage state environments.
+---
+
+# Env Command
+
+The `terraform env` command is used to manage
+[state environments](/docs/state/environments.html).
+
+This command is a nested subcommand, meaning that it has further subcommands.
+These subcommands are listed to the left.
+
+## Usage
+
+Usage: `terraform env <subcommand> [options] [args]`
+
+Please click a subcommand to the left for more information.

website/source/docs/commands/env/list.html.md

@@ -0,0 +1,27 @@
+---
+layout: "commands-env"
+page_title: "Command: env list"
+sidebar_current: "docs-env-sub-list"
+description: |-
+  The terraform env list command is used to list all created state environments.
+---
+
+# Command: env list
+
+The `terraform env list` command is used to list all created state environments.
+
+## Usage
+
+Usage: `terraform env list`
+
+The command will list all created environments. The current environment
+will have an asterisk (`*`) next to it.
+
+## Example
+
+```
+$ terraform env list
+  default
+* development
+  mitchellh-test
+```

website/source/docs/commands/env/new.html.md

@@ -0,0 +1,50 @@
+---
+layout: "commands-env"
+page_title: "Command: env new"
+sidebar_current: "docs-env-sub-new"
+description: |-
+  The terraform env new command is used to create a new state environment.
+---
+
+# Command: env new
+
+The `terraform env new` command is used to create a new state
+environment.
+
+## Usage
+
+Usage: `terraform env new [NAME]`
+
+This command will create a new environment with the given name. This
+environment must not already exist.
+
+If the `-state` flag is given, the state specified by the given path
+will be copied to initialize the state for this new environment.
+
+The command-line flags are all optional. The list of available flags are:
+
+* `-state=path` - Path to a state file to initialize the state of this environment.
+
+## Example: Create
+
+```
+$ terraform env new example
+Created and switched to environment "example"!
+
+You're now on a new, empty environment. Environments isolate their state,
+so if you run "terraform plan" Terraform will not see any existing state
+for this configuration.
+```
+
+## Example: Create from State
+
+To create a new environment from a pre-existing state path:
+
+```
+$ terraform env new -state=old.terraform.tfstate example
+Created and switched to environment "example"!
+
+You're now on a new, empty environment. Environments isolate their state,
+so if you run "terraform plan" Terraform will not see any existing state
+for this configuration.
+```

website/source/docs/commands/env/switch.html.md

@@ -0,0 +1,31 @@
+---
+layout: "commands-env"
+page_title: "Command: env switch"
+sidebar_current: "docs-env-sub-switch"
+description: |-
+  The terraform env switch command is used to switch state environments.
+---
+
+# Command: env switch
+
+The `terraform env switch` command is used to switch to a different
+environment that is already created.
+
+## Usage
+
+Usage: `terraform env switch [NAME]`
+
+This command will switch to another environment. The environment must
+already be created.
+
+## Example
+
+```
+$ terraform env list
+  default
+* development
+  mitchellh-test
+
+$ terraform env switch default
+Switch to environment "default"!
+```

website/source/docs/state/environments.html.md

@@ -52,13 +52,13 @@ Terraform environment.
 An environment alone **should not** be used to manage the difference between
 development, staging, and production. While it is technically possible, it is
 much more manageable and safe to use multiple independently managed Terraform
-modules linked together with
+configurations linked together with
 [terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
 data sources.
 
 The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
 resource accepts an `environment` name to target. Therefore, you can link
-together multiple independently managed Terraform modules with the same
+together multiple independently managed Terraform configurations with the same
 environment easily. But, they can also have different environments.
 
 While environments are available to all,

website/source/layouts/commands-env.erb

@@ -0,0 +1,38 @@
+<% wrap_layout :inner do %>
+	<% content_for :sidebar do %>
+		<div class="docs-sidebar hidden-print affix-top" role="complementary">
+			<ul class="nav docs-sidenav">
+				<li<%= sidebar_current("docs-home") %>>
+					<a href="/docs/commands/index.html">&laquo; Documentation Home</a>
+				</li>
+
+				<li<%= sidebar_current("docs-env-index") %>>
+					<a href="/docs/commands/env/index.html">env Command</a>
+				</li>
+
+				<li<%= sidebar_current(/^docs-env-sub/) %>>
+					<a href="#">Subcommands</a>
+					<ul class="nav nav-visible">
+						<li<%= sidebar_current("docs-env-sub-list") %>>
+							<a href="/docs/commands/env/list.html">list</a>
+						</li>
+
+						<li<%= sidebar_current("docs-env-sub-switch") %>>
+							<a href="/docs/commands/env/switch.html">switch</a>
+						</li>
+
+						<li<%= sidebar_current("docs-env-sub-new") %>>
+							<a href="/docs/commands/env/new.html">new</a>
+						</li>
+
+						<li<%= sidebar_current("docs-env-sub-delete") %>>
+							<a href="/docs/commands/env/delete.html">delete</a>
+						</li>
+					</ul>
+				</li>
+			</ul>
+		</div>
+	<% end %>
+
+	<%= yield %>
+<% end %>

website/source/layouts/docs.erb

@@ -79,6 +79,10 @@
 							<a href="/docs/commands/destroy.html">destroy</a>
 						</li>
 
+						<li<%= sidebar_current("docs-commands-env") %>>
+							<a href="/docs/commands/env/index.html">env</a>
+						</li>
+
 						<li<%= sidebar_current("docs-commands-fmt") %>>
 							<a href="/docs/commands/fmt.html">fmt</a>
 						</li>