terraform/website/docs/cli/cloud/settings.mdx

---
page_title: Connect to HCP Terraform
description: >-
  Learn how to configure the Terraform CLI to connect to HCP Terraform.
---

# Connect to HCP Terraform

This topic describes how to connect the Terraform CLI to HCP Terraform. Integrating the CLI with HCP Terraform enables the CLI to act as a client for CLI-drive workflows. Refer to [CLI-driven Run Workflow](/terraform/cloud-docs/run/cli) for additional information.

> **Hands On:** Complete the [Migrate State to HCP Terraform](/terraform/tutorials/cloud/cloud-migrate) tutorial to learn more about integrating the CLI with HCP Terraform.

## Overview

Connecting the Terraform CLI to HCP Terraform links the working directory that contains your Terraform configurations to one or more HCP Terraform workspaces. This allows team members with access to the workspace to provision and manage infrastructure using HCP Terraform. Additionally, HCP Terraform manages state data so that you do not have to maintain remote state objects. Refer to the following topics for additional information:

- [State overview](/terraform/language/state) in the Terraform configuration language reference.
- [Terraform State in HCP Terraform](/terraform/cloud-docs/workspaces/state) in the HCP Terraform documentation.

Complete the following steps to connect to HCP Terraform:

1. Provide credentials to HCP Terraform.
1. Define connection settings in your Terraform configuration.
1. Initialize the working directory.
1. Migrate state data. This step is optional.

## Requirements

You must have a user profile in HCP Terraform with permissions to create a workspace. Refer to [Workspace Permissions](/terraform/cloud-docs/users-teams-organizations/permissions) in the HCP Terraform documentation for additional information.

## Provide credentials

You must provide credentials to access HCP Terraform. We recommend using the
[`terraform login`](/terraform/cli/commands/login) command to log into Terraform. You can also provide a user token in the Terraform configuration. Refer to the [`token`](/terraform/language/terraform#terraform-cloud-token) attribute in the Terraform configuration reference for additional information.


## Define connection settings

Add a `cloud` block to your Terraform configuration and configure the connection settings to link the working directory to an HCP Terraform workspace. The `cloud` block is a member of the `terraform` block. Refer to the [`terraform` block reference](/terraform/language/terraform) for additional information.

Specify the following settings in the `cloud` block:

- `organization`:  Specifies the name of an HCP Terraform organization to connect to.
- `workspaces.tags`: Specifies a list of single-value string tags. Terraform links the working directory to existing workspaces in the organization that have matching tags. If there are no existing workspaces with matching tags, the Terraform CLI prompts you to create a new workspace that inherits the tags you specify in this field when you initialize the configuration.
- `workspaces.name`: You can specify the name of an existing workspace to associate with the Terraform configuration instead of using tags. If you configure the `name`, you cannot use the `tags` configuration.
- `workspaces.project`: You can specify the name of an existing project. Terraform associates the configuration with workspaces in the project that match the `name` or `tags`. 

Refer to the [`cloud` block reference](/terraform/language/terraform#terraform-cloud) for details about configuring the `cloud` block.

In the following example, the configuration links the working directory to all workspaces tagged with `networking` and `source:cli` in the `networking-development` project:

```hcl
terraform {
  cloud {
    organization = "my-org"
    hostname = "app.terraform.io" # Optional; defaults to app.terraform.io

    workspaces {
      project = "networking-development"
      tags = ["networking", "source:cli"]
    }
  }
}
```

## Initialize the working directory

After adding or changing a `cloud` block, run the [`terraform init` command](/terraform/cli/commands/init) to complete the set up.

By default, Terraform uploads a copy of Terraform configurations stored in the working directory when you run the `terraform plan` or `terraform apply` command, but you can add a `.terraformignore` file to the directory and specify files that you do not want to upload to HCP Terraform. Refer to [Exclude files](#exclude-files) for additional information.

If the working directory does not have an existing Terraform state file, you can immediately start using Terraform with HCP Terraform. Refer to [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for additional information.

If the directory has an existing state file associated with a `backend` configuration, Terraform prompts you to migrate state from any existing workspaces. Refer to [Migrate state data](#migrate-state-data) for next steps.

## Migrate state data

Complete the data migration process when prompted according to one of the following scenarios:

State is stored in a [local or state backend](#local-and-state-backend-migration): If the working directory already has state data in one or more workspaces, Terraform prompts you to migrate the state to new HCP Terraform workspaces.
State is stored in a [remote backend](#remote-backend-migration): If the working directory is already connected to HCP Terraform with the remote backend, Terraform can continue using the same HCP Terraform workspaces. Change the `backend "remote"` configuration to a `cloud` block in this scenario.

### Migrate local state

Run the `terraform init` command and follow the CLI prompts to migrate state data stored in a local or state backend.

HCP Terraform requires all workspaces to have a name. As a result, Terraform may also prompt you to rename your workspaces during the migration.

Terraform CLI-only workspaces represent multiple environments associated with the same configuration, such as `production`, `staging`, and `development`, but HCP Terraform workspaces can represent completely independent configurations and must have unique names within the HCP Terraform organization.

As a result, Terraform prompts you to rename workspaces according to a pattern relative to their existing names. The pattern is intended to indicate that the workspaces share configuration. A common strategy is `<COMPONENT>-<ENVIRONMENT>-<REGION>`, for example `networking-prod-us-east` and `networking-staging-us-east`. Refer to [Workspace Naming](/terraform/cloud-docs/workspaces/naming) in the HCP Terraform documentation for additional information.

### Migrate remote backend

In the `terraform` block or `terraform.tf` file, replace `backend "remote"` with `cloud`. Terraform will continue to use the same ste of HCP Terraform workspaces.

The following example migrates the state data for a single workspace named `my-app-prod` to an HCP Terraform organization named `my-org`.

```hcl
terraform {
-  backend "remote" {
+    cloud {
       organization = "my-org"

       workspaces {
          name = "my-app-prod"
       }
     }
   }
}
```

If the `terraform` block or `terraform.tf` file uses the `prefix` argument to connect to multiple workspaces, you can specify a list of single-value string tags in the `tags` argument instead of using the `name` argument. During `terraform plan` or `terraform apply` operations, Terraform associates the configuration with workspaces that match the specified tags.

The following example replaces the `my-app-` prefix with the `app:mine` tag:

```hcl
terraform {
-  backend "remote" {
+  cloud {
     organization = "my-org"

    workspaces {
-      prefix = "my-app-"
+      tags = ["app:mine"]
    }
   }
 }

```

Note that because the `cloud` block does not support the `prefix` argument, after you migrate your workspaces to HCP Terraform, you must refer to them by their full name when you use the Terraform CLI. For example, instead of running the `terraform workspace select prod` command, you would run `terraform workspace select my-app-prod` instead.

## Exclude files

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, Terraform still excludes the following directories by default:

- `.git/` directories
- `.terraform/` directories (exclusive of `.terraform/modules`)

The rules for defining `.terraformignore` are based on
[.gitignore files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring):

- Terraform ignores comments starting with `#`
- Terraform ignores blank lines.
- 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.

Terraform parses the `.terraformignore` at the root of the configuration directory.