---
page_title: Cloud Backend Settings - OpenTF CLI
description: >-
  Configure the Cloud Backend CLI integration.
---

# Cloud Backend Settings

OpenTF CLI can integrate with a cloud backend, acting as a client for it.

You must configure the following settings to use the cloud backend for a particular working directory:

- Provide credentials to access the cloud backend, preferably by using the
  [`opentf login`](/opentf/cli/commands/login) command.
- Add a `cloud` block to the directory's OpenTF 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 OpenTF configuration when running plans and applies.

After adding or changing a `cloud` block, you must run `opentf init`.

## The `cloud` Block

The `cloud` block is a nested block within the top-level `terraform` settings
block. It specifies which cloud backend workspaces to use for the current
working directory.

```hcl
terraform {
  cloud {
    organization = "my-org"
    hostname = "app.example.org" # 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](/opentf/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 OpenTF CLI's behavior. When the cloud backend 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 cloud backend 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 cloud backend 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 `opentf workspace` commands](/opentf/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 cloud backend 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. `opentf workspace select` or
    `opentf workspace new`). This option conflicts with `tags`.

  - `project` - (Optional) The name of a cloud backend project. Workspaces that need created will
    will be created within this project. `opentf workspace list` will be filtered by workspaces
    in the supplied project.

- `hostname` - (Optional) The hostname of the cloud backend.

- `token` - (Optional) The token used to authenticate with the cloud backend.
  We recommend omitting the token from the configuration, and instead using
  [`opentf login`](/opentf/cli/commands/login) or manually configuring
  `credentials` in the
  [CLI config file](/opentf/cli/config/config-file#credentials).

### Environment Variables

You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure OpenTF as part of a Continuous Integration (CI) pipeline. OpenTF 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.

Use the following environment variables to configure the `cloud` block:

- `TF_CLOUD_ORGANIZATION` - The name of the organization. OpenTF reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence.

- `TF_CLOUD_HOSTNAME` - The hostname of the cloud backend. OpenTF reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence.

- `TF_CLOUD_PROJECT` - The name of a cloud backend project. OpenTF 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 cloud backend workspace. OpenTF reads this when `workspaces` is omitted from the `cloud` block. The cloud backend 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](/opentf/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,
a copy of your configuration directory is uploaded to the cloud backend. 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.