| --- |
| page_title: Terraform Cloud Settings - Terraform CLI |
| description: >- |
| Configure the Terraform Cloud CLI integration. |
| --- |
| |
| # Terraform Cloud Settings |
| |
| Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's |
| [CLI-driven run workflow](/cloud-docs/run/cli). |
| |
| > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial. |
| |
| You must configure the following settings to use Terraform Cloud for a particular working directory: |
| |
| - Provide credentials to access Terraform Cloud, preferably by using the |
| [`terraform login`](/cli/commands/login) command. |
| - Add a `cloud` block to the directory's Terraform configuration, to specify |
| which organization and workspace(s) to use. |
| - Optionally, use a `.terraformignore` file to specify files that shouldn't be |
| uploaded with the Terraform configuration when running plans and applies. |
| |
| After adding or changing a `cloud` block, you must run `terraform init`. |
| |
| ## The `cloud` Block |
| |
| The `cloud` block is a nested block within the top-level `terraform` settings |
| block. It specifies which Terraform Cloud workspaces to use for the current |
| working directory. |
| |
| ```hcl |
| terraform { |
| cloud { |
| organization = "my-org" |
| hostname = "app.terraform.io" # Optional; defaults to app.terraform.io |
| |
| workspaces { |
| tags = ["networking", "source:cli"] |
| } |
| } |
| } |
| ``` |
| |
| The `cloud` block also has some special restrictions: |
| |
| - A configuration can only provide one `cloud` block. |
| - A `cloud` block cannot be used with [state backends](/language/settings/backends/configuration). |
| A configuration can use one or the other, but not both. |
| - A `cloud` block cannot refer to named values (like input variables, locals, or |
| data source attributes). |
| |
| The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration |
| that contains a cloud block - for example, when a workspace is configured to use a VCS provider |
| directly - it ignores the block and behaves according to its own workspace settings. |
| |
| ### Arguments |
| |
| The `cloud` block supports the following configuration arguments: |
| |
| - `organization` - (Required) The name of the organization containing the |
| workspace(s) the current configuration should use. |
| |
| - `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to |
| use for the current configuration. The `workspaces` block must contain **exactly one** of the |
| following arguments, each denoting a strategy for how workspaces should be mapped: |
| |
| - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use |
| this working directory with any workspaces that have all of the specified tags, |
| and can use [the `terraform workspace` commands](/cli/workspaces) |
| to switch between them or create new workspaces. New workspaces will automatically have |
| the specified tags. This option conflicts with `name`. |
| |
| - `name` - (Optional) The name of a single Terraform Cloud workspace. You will |
| only be able to use the workspace specified in the configuration with this working |
| directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or |
| `terraform workspace new`). This option conflicts with `tags`. |
| |
| - `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform |
| Enterprise. Defaults to Terraform Cloud (app.terraform.io). |
| |
| - `token` - (Optional) The token used to authenticate with Terraform Cloud. |
| We recommend omitting the token from the configuration, and instead using |
| [`terraform login`](/cli/commands/login) or manually configuring |
| `credentials` in the |
| [CLI config file](/cli/config/config-file#credentials). |
| |
| ### Environment Variables |
| |
| -> **Note:** CLI integration environment variables are supported in Terraform v1.2.0 and later. |
| |
| You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file. |
| |
| ~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to [Non-Interactive Workflows](/cloud-docs/run/cli#non-interactive-workflows) for details. |
| |
| Use the following environment variables to configure the `cloud` block: |
| |
| - `TF_CLOUD_ORGANIZATION` - The name of the organization. Terraform reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence. |
| |
| - `TF_CLOUD_HOSTNAME` - The hostname of a Terraform Enterprise installation. Terraform reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence. |
| |
| - `TF_WORKSPACE` - The name of a single Terraform Cloud workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. Terraform Cloud will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/cli/config/environment-variables#tf_workspace) for details. |
| |
| ## Excluding Files from Upload with .terraformignore |
| |
| When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli), |
| a copy of your configuration directory is uploaded to Terraform Cloud. You can define |
| paths to exclude from upload by adding a `.terraformignore` file at the root of your |
| configuration directory. If this file is not present, the upload will exclude |
| the following by default: |
| |
| - `.git/` directories |
| - `.terraform/` directories (exclusive of `.terraform/modules`) |
| |
| The rules in `.terraformignore` file resemble the rules allowed in a |
| [.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring): |
| |
| - Comments (starting with `#`) or blank lines are ignored. |
| - End a pattern with a forward slash `/` to specify a directory. |
| - Negate a pattern by starting it with an exclamation point `!`. |
| |
| -> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered. |