opentf/website/docs/cli/config/config-file.mdx

---
title: CLI Configuration File
description: >-
  Learn to use the CLI configuration file to customize your CLI settings,
  including credentials, plugin caching, provider installation methods, etc.
---

# CLI Configuration File (`.tofurc` or `tofu.rc`)

The CLI configuration file configures per-user settings for CLI behaviors,
which apply across all OpenTofu working directories. This is separate from
[your infrastructure configuration](../../language/index.mdx).

## Locations

The configuration can be placed in a single file whose location depends
on the host operating system:

* On Windows, the file must be named `tofu.rc` and placed
  in the relevant user's `%APPDATA%` directory. The physical location
  of this directory depends on your Windows version and system configuration;
  use `$env:APPDATA` in PowerShell to find its location on your system.
  The `terraform.rc` is supported for backward-compatibility purposes.
  If both `terraform.rc` and `tofu.rc` files exists, the later would take precedence.
* On all other systems, the file must be named `.tofurc` (note
  the leading period) and placed directly in the home directory
  of the relevant user or be named `tofurc` and placed in a valid
  [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
  config directory such as `$XDG_CONFIG_HOME/opentofu`.
  The `.terraformrc` is supported for backward-compatibility purposes.
  If both `.terraformrc` and `.tofurc` files exists, the latter would take precedence.
  When using an XDG config directory `.terraformrc` and `terraformrc` are ignored.

On Windows, beware of Windows Explorer's default behavior of hiding filename
extensions. OpenTofu will not recognize a file named `tofuc.rc.txt` as a
CLI configuration file, even though Windows Explorer may _display_ its name
as just `tofu.rc`. Use `dir` from PowerShell or Command Prompt to
confirm the filename.

The location of the OpenTofu CLI configuration file can also be specified
using the `TF_CLI_CONFIG_FILE` [environment variable](environment-variables.mdx).
Any such file should follow the naming pattern `*.tfrc`.

## Configuration File Syntax

The configuration file uses the same _HCL_ syntax as `.tf` and `.tofu` files,
but with different attributes and blocks. The following example illustrates the
general syntax; see the following section for information on the meaning
of each of these settings:

```hcl
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
```

## Available Settings

The following settings can be set in the CLI configuration file:

* `credentials` - configures credentials for use with a cloud backend.
  See [Credentials](#credentials) below for more information.

* `credentials_helper` - configures an external helper program for the storage
  and retrieval of credentials for cloud backends.
  See [Credentials Helpers](#credentials-helpers) below for more information.

* `oci_credentials` and `default_oci_credentials` - configures credentials for
  interacting with an OCI Registry. Refer to
  [OCI Registry Credentials](../oci_registries/credentials.mdx) for more information.

* `plugin_cache_dir` — enables
  [plugin caching](#provider-plugin-cache)
  and specifies, as a string, the location of the plugin cache directory.

* `provider_installation` - customizes the installation methods used by
  `tofu init` when installing provider plugins. See
  [Provider Installation](#provider-installation) below for more information.

* `registry_protocols` - configures some infrequently-needed settings
  controlling how OpenTofu requests metadata from module and provider
  registries.
  Refer to [Registry Protocol Settings](#registry-protocol-settings) below for more information.

## Credentials

When interacting with OpenTofu-specific network services, OpenTofu expects
to find API tokens in CLI configuration files in `credentials` blocks:

```hcl
credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}
```

If you are running the OpenTofu CLI interactively on a computer with a web browser, you can use [the `tofu login` command](../commands/login.mdx)
to get credentials and automatically save them in the CLI configuration. If
not, you can manually write `credentials` blocks.

You can have multiple `credentials` blocks if you regularly use services from
multiple hosts. Each `credentials` block contains a `token` argument
giving the API token to use for that host.

:::note
The credentials hostname must match the hostname in your module
sources and/or backend configuration.
:::

`credentials` blocks are used only for OpenTofu-specific protocols. You can
configure credentials for OCI Registries using `oci_credentials` blocks,
as described in [OCI Registry Credentials](../oci_registries/credentials.mdx).

### Environment Variable Credentials

If you would prefer not to store your API tokens directly in the CLI configuration, you may use
a host-specific environment variable. Environment variable names should have the prefix
`TF_TOKEN_` added to the domain name, with periods encoded as underscores. For example, the
value of a variable named `TF_TOKEN_app_opentofu_org` will be used as a bearer authorization
token when the CLI makes service requests to the hostname `app.opentofu.org`.

You must convert domain names containing non-ASCII characters to their [punycode equivalent](https://www.charset.org/punycode)
with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable
called `TF_TOKEN_xn--r8j3dr99h_com`.

Hyphens are also valid within host names but usually invalid as variable names and
may be encoded as double underscores. For example, you can set a token for the domain name
`café.fr` as `TF_TOKEN_xn--caf-dma.fr`, `TF_TOKEN_xn--caf-dma_fr`,  or `TF_TOKEN_xn____caf__dma_fr`.
If multiple variables evaluate to the same hostname, OpenTofu will choose the one defined last
in the operating system's variable table.

### Credentials Helpers

You can configure a `credentials_helper` to instruct OpenTofu to use a different credentials storage mechanism.

```hcl
credentials_helper "example" {
  args = []
}
```

`credentials_helper` is a configuration block that can appear at most once
in the CLI configuration. Its label (`"example"` above) is the name of the
credentials helper to use. The `args` argument is optional and allows passing
additional arguments to the helper program, for example if it needs to be
configured with the address of a remote host to access for credentials.

A configured credentials helper will be consulted only to retrieve credentials
for hosts that are _not_ explicitly configured in a `credentials` block as
described in the previous section.
Conversely, this means you can override the credentials returned by the helper
for a specific hostname by writing a `credentials` block alongside the
`credentials_helper` block.

OpenTofu does not include any credentials helpers in the main distribution.
To learn how to write and install your own credentials helpers to integrate
with existing in-house credentials management systems, see
[the guide to Credentials Helper internals](../../internals/credentials-helpers.mdx).

### Credentials Source Priority Order

Credentials found in an environment variable for a particular service host
as described above will be preferred over those in CLI config as set by `tofu login`.
If neither are set, any configured credentials helper will be consulted.

## Provider Installation

The default way to install provider plugins is from a provider registry. The
origin registry for a provider is encoded in the provider's source address,
like `registry.opentofu.org/hashicorp/aws`. For convenience in the common case,
OpenTofu allows omitting the hostname portion for providers on
`registry.opentofu.org`, so you can write shorter public provider addresses like
`hashicorp/aws`.

Downloading a plugin directly from its origin registry is not always
appropriate, though. For example, the system where you are running OpenTofu
may not be able to access an origin registry due to firewall restrictions
within your organization or your locality.

To allow using OpenTofu providers in these situations, there are some
alternative options for making provider plugins available to OpenTofu which
we'll describe in the following sections.

### Explicit Installation Method Configuration

A `provider_installation` block in the CLI configuration allows overriding
OpenTofu's default installation behaviors, so you can force OpenTofu to use
a local mirror for some or all of the providers you intend to use.

The general structure of a `provider_installation` block is as follows:

```hcl
provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}
```

Each of the nested blocks inside the `provider_installation` block specifies
one installation method. Each installation method can take both `include`
and `exclude` patterns that specify which providers a particular installation
method can be used for. In the example above, we specify that any provider
whose origin registry is at `example.com` can be installed only from the
filesystem mirror at `/usr/share/terraform/providers`, while all other
providers can be installed only directly from their origin registries.

If you set both `include` and `exclude` for a particular installation
method, the exclusion patterns take priority. For example, including
`registry.opentofu.org/hashicorp/*` but also excluding
`registry.opentofu.org/hashicorp/dns` will make that installation method apply
to everything in the `hashicorp` namespace with the exception of
`hashicorp/dns`.

As with provider source addresses in the main configuration, you can omit
the `registry.opentofu.org/` prefix for providers distributed through the
public OpenTofu Registry, even when using wildcards. For example,
`registry.opentofu.org/hashicorp/*` and `hashicorp/*` are equivalent.
`*/*` is a shorthand for `registry.opentofu.org/*/*`, not for
`*/*/*`.

The following are the supported installation method types:

* `direct`: request information about the provider directly from its origin
  registry and download over the network from the location that registry
  indicates. This method expects no additional arguments.

* `filesystem_mirror`: consult a directory on the local disk for copies of
  providers. This method requires the additional argument `path` to indicate
  which directory to look in.

  OpenTofu expects the given directory to contain a nested directory structure
  where the path segments together provide metadata about the available
  providers. The following two directory structures are supported:

  * Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip`
    is the distribution zip file obtained from the provider's origin registry.
  * Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory
    containing the result of extracting the provider's distribution zip file.

  In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET`
  specifies a particular target platform using a format like `darwin_amd64`,
  `linux_arm`, `windows_amd64`, etc.

  If you use the unpacked layout, OpenTofu will attempt to create a symbolic
  link to the mirror directory when installing the provider, rather than
  creating a deep copy of the directory. The packed layout prevents this
  because OpenTofu must extract the zip file during installation.

  You can include multiple `filesystem_mirror` blocks in order to specify
  several different directories to search.

* `network_mirror`: consult a particular HTTPS server for copies of providers,
  regardless of which registry host they belong to. This method requires the
  additional argument `url` to indicate the mirror base URL, which should
  use the `https:` scheme and end with a trailing slash.

  OpenTofu expects the given URL to be a base URL for an implementation of
  [the provider network mirror protocol](../../internals/provider-network-mirror-protocol.mdx),
  which is designed to be relatively easy to implement using typical static
  website hosting mechanisms.

* `oci_mirror`: map provider source addresses into OCI repository addresses,
  regardless of which registry host they belong to, and then retrieve them
  using the OCI Distribution protocol.

  This is similar to `network_mirror`, but uses the industry-standard OCI
  registry protocol instead of the OpenTofu-specific provider network
  mirror protocol to allow you to reuse a pre-existing OCI registry service.

  For more information, refer to [Provider Mirrors in OCI Registries](../oci_registries/provider-mirror.mdx).

:::warning
Don't configure `network_mirror` URLs that you do not trust.
Provider mirror servers are subject to TLS certificate checks to verify
identity, but a network mirror with a TLS certificate can potentially serve
modified copies of upstream providers with malicious content.
:::

The `direct` and `network_mirror` methods support an additional argument
`download_retry_count`. When specified, it will be used to retry downloading
the provider binary in case of retryable errors (connection reset and a range of 500 errors).
```hcl
provider_installation {
  network_mirror {
    url                  = "https://example.com/"
    include              = ["example.com/*/*"]
    download_retry_count = 2
  }
  direct {
    exclude              = ["example.com/*/*"]
    download_retry_count = 3
  }
}
```
You can use this argument to disable fully the retries in case of a specific method (`download_retry_count = 0`).
:::info
When used together with [`TF_PROVIDER_DOWNLOAD_RETRY`](./environment-variables.mdx#tf_provider_download_retry), the configuration value
will be used for each method that it is configured with. For the methods
with no such configuration, the environment variable will be used instead.
:::

OpenTofu will try all of the specified methods whose include and exclude
patterns match a given provider, and select the newest version available across
all of those methods that matches the version constraint given in each
OpenTofu configuration. If you have a local mirror of a particular provider
and intend OpenTofu to use that local mirror exclusively, you must either
remove the `direct` installation method altogether or use its `exclude`
argument to disable its use for specific providers.

### Implied Local Mirror Directories

If your CLI configuration does not include a `provider_installation` block at
all, OpenTofu produces an _implied_ configuration. The implied configuration
includes a selection of `filesystem_mirror` methods and then the `direct`
method.

The set of directories OpenTofu can select as filesystem mirrors depends on
the operating system where you are running OpenTofu:

* **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins`
* **Mac OS X:** `$HOME/.terraform.d/plugins`,
  `~/Library/Application Support/io.terraform/plugins`, and
  `/Library/Application Support/io.terraform/plugins`
* **Linux and other Unix-like systems**:`$HOME/.terraform.d/plugins` and
  `opentofu/plugins` located within a valid
  [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
  data directory such as `$XDG_DATA_HOME/opentofu/plugins`.

If a `terraform.d/plugins` directory exists in the current working directory
then OpenTofu will also include that directory, regardless of your operating
system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, OpenTofu checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`.

OpenTofu will check each of the paths above to see if it exists, and if so
treat it as a filesystem mirror. The directory structure inside each one must
therefore match one of the two structures described for `filesystem_mirror`
blocks in [Explicit Installation Method Configuration](#explicit-installation-method-configuration).

In addition to the zero or more implied `filesystem_mirror` blocks, OpenTofu
also creates an implied `direct` block. OpenTofu will scan all of the
filesystem mirror directories to see which providers are placed there and
automatically exclude all of those providers from the implied `direct` block.
(This automatic `exclude` behavior applies only to _implicit_ `direct` blocks;
if you use explicit `provider_installation` you will need to write the intended
exclusions out yourself.)

### Provider Plugin Cache

By default, `tofu init` downloads plugins into a subdirectory of the
working directory so that each working directory is self-contained. As a
consequence, if you have multiple configurations that use the same provider
then a separate copy of its plugin will be downloaded for each configuration.

Given that provider plugins can be quite large (on the order of hundreds of
megabytes), this default behavior can be inconvenient for those with slow
or metered Internet connections. Therefore OpenTofu optionally allows the
use of a local directory as a shared plugin cache, which then allows each
distinct plugin binary to be downloaded only once.

To enable the plugin cache, use the `plugin_cache_dir` setting in
the CLI configuration file. For example:

```hcl
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
```

This directory must already exist before OpenTofu will cache plugins;
OpenTofu will not create the directory itself.

Please note that on Windows it is necessary to use forward slash separators
(`/`) rather than the conventional backslash (`\`) since the configuration
file parser considers a backslash to begin an escape sequence.

Setting this in the configuration file is the recommended approach for a
persistent setting. Alternatively, the `TF_PLUGIN_CACHE_DIR` environment
variable can be used to enable caching or to override an existing cache
directory within a particular shell session:

```bash
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
```

When a plugin cache directory is enabled, the `tofu init` command will
still use the configured or implied installation methods to obtain metadata
about which plugins are available, but once a suitable version has been
selected it will first check to see if the chosen plugin is already available
in the cache directory. If so, OpenTofu will use the previously-downloaded
copy.

If the selected plugin is not already in the cache, OpenTofu will download
it into the cache first and then copy it from there into the correct location
under your current working directory. When possible OpenTofu will use
symbolic links to avoid storing a separate copy of a cached plugin in multiple
directories.

The plugin cache directory _must not_ also be one of the configured or implied
filesystem mirror directories, since the cache management logic conflicts with
the filesystem mirror logic when operating on the same directory.

OpenTofu will never itself delete a plugin from the plugin cache once it has
been placed there. Over time, as plugins are upgraded, the cache directory may
grow to contain several unused versions which you must delete manually.

:::note
The plugin cache directory makes a best effort to be concurrency
safe. It uses standard file locking practices (fnctl flock or LockFileEx),
which have different guarantees depending on Operating System and filesystem.
:::

### Allowing the Provider Plugin Cache to break the dependency lock file

:::warning Note
The option described in is for unusual and exceptional situations
only. Do not set this option unless you are sure you need it and you fully
understand the consequences of enabling it.
:::

By default OpenTofu will use packages from the global cache directory only
if they match at least one of the checksums recorded in the
[dependency lock file](../../language/files/dependency-lock.mdx)
for that provider. This ensures that OpenTofu can always
generate a complete and correct dependency lock file entry the first time you
use a new provider in a particular configuration.

However, we know that in some special situations teams have been unable to use
the dependency lock file as intended, and so they don't include it in their
version control as recommended and instead let OpenTofu re-generate it each
time it installs providers.

For those teams that don't preserve the dependency lock file in their version
control systems between runs, OpenTofu allows an additional CLI Configuration
setting which tells OpenTofu to always treat a package in the cache directory
as valid even if there isn't already an entry in the dependency lock file
to confirm it:

```hcl
plugin_cache_may_break_dependency_lock_file = true
```

Alternatively, you can set the environment variable
`TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to any value other than the
empty string or `0`, which is equivalent to the above setting.

Setting this option gives OpenTofu CLI permission to create an incomplete
dependency lock file entry for a provider if that would allow OpenTofu to
use the cache to install that provider. In that situation the dependency lock
file will be valid for use on the current system but may not be valid for use on
another computer with a different operating system or CPU architecture, because
it will include only a checksum of the package in the global cache.

We recommend that most users leave this option unset, in which case OpenTofu
will always install a provider from upstream the first time you use it with
a particular configuration, but can then re-use the cache entry on later runs
once the dependency lock file records valid checksums for the provider package.

:::warning Note
The OpenTofu team intends to improve the dependency lock file
mechanism in future versions so that it will be usable in more situations. At
that time this option will become silently ignored. If your workflow relies on
the use of this option, please open a GitHub issue to share details about your
situation so that we can consider how to support it without breaking the
dependency lock file.
:::

### Development Overrides for Provider Developers

Normally OpenTofu verifies version selections and checksums for providers
in order to help ensure that all operations are made with the intended version
of a provider, and that authors can gradually upgrade to newer provider versions
in a controlled manner.

These version and checksum rules are inconvenient when developing a provider
though, because we often want to try a test configuration against a development
build of a provider that doesn't even have an associated version number yet,
and doesn't have an official set of checksums listed in a provider registry.

As a convenience for provider development, OpenTofu supports a special
additional block `dev_overrides` in `provider_installation` blocks. The contents
of this block effectively override all of the other configured installation
methods, so a block of this type must always appear first in the sequence:

```hcl
provider_installation {

  # Use /home/developer/tmp/terraform-null as an overridden package directory
  # for the hashicorp/null provider. This disables the version and checksum
  # verifications for this provider and forces OpenTofu to look for the
  # null provider plugin in the given directory.
  dev_overrides {
    "hashicorp/null" = "/home/developer/tmp/terraform-null"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, OpenTofu will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}
```

With development overrides in effect, the `tofu init` command will still
attempt to select a suitable published version of your provider to install and
record in
[the dependency lock file](../../language/files/dependency-lock.mdx)
for future use, but other commands like
`tofu apply` will disregard the lock file's entry for `hashicorp/null` and
will use the given directory instead. Once your new changes are included in a
published release of the provider, you can use `tofu init -upgrade` to
select the new version in the dependency lock file and remove your development
override.

The override path for a particular provider should be a directory similar to
what would be included in a `.zip` file when distributing the provider. At
minimum that includes an executable file named with a prefix like
`terraform-provider-null`, where `null` is the provider type. If your provider
makes use of other files in its distribution package then you can copy those
files into the override directory too.

You may wish to enable a development override only for shell sessions where
you are actively working on provider development. If so, you can write a
local CLI configuration file with content like the above in your development
directory, perhaps called `dev.tfrc` for the sake of example, and then use the
`TF_CLI_CONFIG_FILE` environment variable to instruct OpenTofu to use that
localized CLI configuration instead of the default one:

```
export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc
```

Development overrides are not intended for general use as a way to have
OpenTofu look for providers on the local filesystem. If you wish to put
copies of _released_ providers in your local filesystem, see
[Implied Local Mirror Directories](#implied-local-mirror-directories)
or
[Explicit Installation Method Configuration](#explicit-installation-method-configuration)
instead.

This development overrides mechanism is intended as a pragmatic way to enable
smoother provider development. The details of how it behaves, how to
configure it, and how it interacts with the dependency lock file may all evolve
in future OpenTofu releases, including possible breaking changes. We therefore
recommend using development overrides only temporarily during provider
development work.

## Registry Protocol Settings

The CLI configuration block `registry_protocols` controls a small number of
rarely-needed settings for customizing the retry behavior and request timeouts
when OpenTofu makes metadata requests to module and provider registries.

```hcl
registry_protocols {

  # retry_count specifies how many times OpenTofu can
  # retry a registry metadata request when the response
  # is a retry-eligible error.
  #
  # This can also be set using an environment variable:
  #    TF_REGISTRY_DISCOVERY_RETRY=1
  retry_count = 1

  # request_timeout_seconds specifies how long OpenTofu
  # should wait for a response to a registry metadata
  # request, in seconds.
  #
  # This can also be set using an environment variable:
  #    TF_REGISTRY_CLIENT_TIMEOUT=10
  request_timeout_seconds = 10

}
```

The values in the example above are the current defaults, although the
defaults are subject to change in future versions of OpenTofu.

These settings are used only when making requests to the _OpenTofu-native_
registry protocols, and when performing service discovery to find service
endpoints for a particular hostname.

These settings do not affect any other requests made by OpenTofu, including
requests to download the actual module or provider packages, or requests to
other kinds of installation sources such as OCI registries.