website: document init and new state commands

website/source/docs/commands/init.html.markdown

@@ -3,62 +3,71 @@ layout: "docs"
 page_title: "Command: init"
 sidebar_current: "docs-commands-init"
 description: |-
-  The `terraform init` command is used to initialize a Terraform configuration using another module as a skeleton.
+  The `terraform init` command is used to initialize a Terraform configuration. This is the first command that should be run for any new or existing Terraform configuration. It is safe to run this command multiple times.
 ---
 
 # Command: init
 
-The `terraform init` command is used to initialize a Terraform configuration
-using another
-[module](/docs/modules/index.html)
-as a skeleton.
+The `terraform init` command is used to initialize a Terraform configuration.
+This is the first command that should be run for any new or existing
+Terraform configuration. It is safe to run this command multiple times.
 
 ## Usage
 
-Usage: `terraform init [options] SOURCE [DIR]`
+Usage: `terraform init [options] [SOURCE] [PATH]`
 
-Init will download the module from SOURCE and copy it into the DIR
-(which defaults to the current working directory). Version control
-information from the module (such as Git history) will not be copied.
+Initialize a new or existing Terraform environment by creating
+initial files, loading any remote state, downloading modules, etc.
 
-The directory being initialized must be empty of all Terraform configurations.
-If the module has other files which conflict with what is already in the
-directory, they _will be overwritten_.
+This is the first command that should be run for any new or existing
+Terraform configuration per machine. This sets up all the local data
+necessary to run Terraform that is typically not comitted to version
+control.
 
-The command-line options available are a subset of the ones for the
-[remote command](/docs/commands/remote.html), and are used to initialize
-a remote state configuration if provided.
+This command is always safe to run multiple times. Though subsequent runs
+may give errors, this command will never blow away your environment or state.
+Even so, if you have important information, please back it up prior to
+running this command just in case.
+
+If no arguments are given, the configuration in this working directory
+is initialized.
+
+If one or two arguments are given, the first is a SOURCE of a module to
+download to the second argument PATH. After downloading the module to PATH,
+the configuration will be initialized as if this command were called pointing
+only to that PATH. PATH must be empty of any Terraform files. Any
+conflicting non-Terraform files will be overwritten. The module download
+is a copy. If you're downloading a module from Git, it will not preserve
+Git history.
 
 The command-line flags are all optional. The list of available flags are:
 
-* `-backend=atlas` - Specifies the type of remote backend. Must be one
-  of Atlas, Consul, S3, or HTTP. Defaults to Atlas.
+* `-backend=true` - Initialize the [backend](/docs/backends) for this environment.
 
-* `-backend-config="k=v"` - Specify a configuration variable for a backend. This is how you set the required variables for the selected backend (as detailed in the [remote command documentation](/docs/commands/remote.html).
+* `-backend-config=path` - Path to an HCL file with additional configuration
+  for the backend. This is merged with the backend in the Terraform configuration.
 
+* `-get=true` - Download any modules for this configuration.
 
-## Example: Consul
+* `-input=true` - Ask for input interactively if necessary. If this is false
+  and input is required, `init` will error.
 
-This example will initialize the current directory and configure Consul remote storage:
+## Backend Config File
 
-```
-$ terraform init \
-    -backend=consul \
-    -backend-config="address=your.consul.endpoint:443" \
-    -backend-config="scheme=https" \
-    -backend-config="path=tf/path/for/project" \
-    /path/to/source/module
-```
+The `-backend-config` path can be used to specify additional
+backend configuration when [initialize a backend](/docs/backends/init.html).
 
-## Example: S3
+This is particularly useful for
+[partial configuration of backends](/docs/backends/config.html). Partial
+configuration lets you keep sensitive information out of your Terraform
+configuration.
 
-This example will initialize the current directory and configure S3 remote storage:
+The backend configuration file is a basic HCL file with key/value pairs.
+The keys are configuration keys for your backend. You do not need to wrap it
+in a `terraform` block. For example, the following file is a valid backend
+configuration file for the Consul backend type:
 
-```
-$ terraform init \
-    -backend=s3 \
-    -backend-config="bucket=your-s3-bucket" \
-    -backend-config="key=tf/path/for/project.json" \
-    -backend-config="acl=bucket-owner-full-control" \
-    /path/to/source/module
+```hcl
+address = "demo.consul.io"
+path    = "newpath"
 ```

website/source/docs/commands/state/pull.html.md

@@ -0,0 +1,24 @@
+---
+layout: "commands-state"
+page_title: "Command: state pull"
+sidebar_current: "docs-state-sub-pull"
+description: |-
+  The `terraform state pull` command is used to manually download and output the state from remote state.
+---
+
+# Command: state pull
+
+The `terraform state pull` command is used to manually download and output
+the state from [remote state](/docs/state/remote.html). This command also
+works with local state.
+
+## Usage
+
+Usage: `terraform state pull`
+
+This command will download the state from its current location and
+output the raw format to stdout.
+
+This is useful for reading values out of state (potentially pairing this
+command with something like [jq](https://stedolan.github.io/jq/)). It is
+also useful if you need to make manual modifications to state.

website/source/docs/commands/state/push.html.md

@@ -0,0 +1,40 @@
+---
+layout: "commands-state"
+page_title: "Command: state push"
+sidebar_current: "docs-state-sub-push"
+description: |-
+  The `terraform state rm` command removes items from the Terraform state.
+---
+
+# Command: state push
+
+The `terraform state push` command is used to manually upload a local
+state file to [remote state](/docs/state/remote.html). This command also
+works with local state.
+
+This command should rarely be used. It is meant only as a utility in case
+manual intervention is necessary with the remote state.
+
+## Usage
+
+Usage: `terraform state push [options] PATH`
+
+This command will push the state specified by PATH to the currently
+configured [backend](/docs/backends).
+
+Terraform will perform a number of safety checks to prevent you from
+making changes that appear to be unsafe:
+
+  * **Differing lineage**: If the "lineage" value in the state differs,
+    Terraform will not allow you to push the state. A differing lineage
+    suggests that the states are completely different and you may lose
+    data.
+
+  * **Higher remote serial**: If the "serial" value in the destination state
+    is higher than the state being pushed, Terraform will prevent the push.
+    A higher serial suggests that data is in the destination state that isn't
+    accounted for in the local state being pushed.
+
+Both of these safety checks can be disabled with the `-force` flag.
+**This is not recommended.** If you disable the safety checks and are
+pushing state, the destination state will be overwritten.

website/source/layouts/commands-state.erb

@@ -24,7 +24,15 @@
 						<li<%= sidebar_current("docs-state-sub-mv") %>>
 							<a href="/docs/commands/state/mv.html">mv</a>
 						</li>
-						
+
+						<li<%= sidebar_current("docs-state-sub-pull") %>>
+							<a href="/docs/commands/state/pull.html">pull</a>
+						</li>
+
+						<li<%= sidebar_current("docs-state-sub-push") %>>
+							<a href="/docs/commands/state/push.html">push</a>
+						</li>
+
 						<li<%= sidebar_current("docs-state-sub-rm") %>>
 							<a href="/docs/commands/state/rm.html">rm</a>
 						</li>