---
page_title: HCP Terraform Settings - Terraform CLI
description: >-
  Configure the HCP Terraform CLI integration.
---

# HCP Terraform Settings

Terraform CLI can integrate with HCP Terraform, acting as a client for HCP Terraform's
[CLI-driven run workflow](/terraform/cloud-docs/run/cli).

> **Hands On:** Try the [Migrate State to HCP Terraform](/terraform/tutorials/cloud/cloud-migrate) tutorial.

You must configure the following settings to use HCP Terraform for a particular working directory:

- Provide credentials to access HCP Terraform, preferably by using the
  [`terraform login`](/terraform/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 HCP Terraform 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 {
      project = "networking-development"
      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](/terraform/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 HCP Terraform 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 HCP Terraform workspaces to
  use for the current configuration. The `workspaces` block must contain **exactly one** of either `tags`
  or `name` argument, each denoting a strategy for how workspaces should be mapped:

  - `tags` - (Optional) A set of HCP Terraform 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](/terraform/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 HCP Terraform 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`.

  - `project` - (Optional) The name of an HCP Terraform project. Workspaces that need creating
    will be created within this project. `terraform workspace list` will be filtered by workspaces
    in the supplied project.

- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
  Enterprise. Defaults to HCP Terraform (app.terraform.io).

- `token` - (Optional) The token used to authenticate with HCP Terraform.
  We recommend omitting the token from the configuration, and instead using
  [`terraform login`](/terraform/cli/commands/login) or manually configuring
  `credentials` in the
  [CLI config file](/terraform/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](/terraform/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_CLOUD_PROJECT` - The name of an HCP Terraform project. Terraform reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence.

- `TF_WORKSPACE` - The name of a single HCP Terraform workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. HCP Terraform 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](/terraform/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](/terraform/cloud-docs/run/cli),
a copy of your configuration directory is uploaded to HCP Terraform. 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 `!`. When ignoring large directories, negation patterns can impact performance. Place negation rules as early as possible within `.terraformignore` or avoid using them if possible.

-> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.