---
description: >-
  Configure the Cloud Backend CLI integration.
---

# Cloud Backend Settings

OpenTofu 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
  [`tofu login`](../commands/login.mdx) command.
- Add a `cloud` block to the directory's OpenTofu 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 OpenTofu configuration when running plans and applies.

After adding or changing a `cloud` block, you must run `tofu 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"

    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](../../language/settings/backends/configuration.mdx).
  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 OpenTofu 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:

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

- `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 `tofu workspace` commands](../workspaces/index.mdx)
    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. `tofu workspace select` or
    `tofu 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. `tofu workspace list` will be filtered by workspaces
    in the supplied project.

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

### Environment Variables

You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure OpenTofu as part of a Continuous Integration (CI) pipeline. OpenTofu 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. OpenTofu 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. OpenTofu 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. OpenTofu 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. OpenTofu 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 selected `TF_WORKSPACE` must have a set of tags that match the tags in the `cloud` block. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](../config/environment-variables.mdx#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.
:::