158 lines
6.8 KiB
Markdown
158 lines
6.8 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "CLI Configuration"
|
|
sidebar_current: "docs-commands-cli-config"
|
|
description: |-
|
|
The general behavior of the Terraform CLI can be customized using the CLI
|
|
configuration file.
|
|
---
|
|
|
|
# CLI Configuration File (`.terraformrc` or `terraform.rc`)
|
|
|
|
The CLI configuration file configures per-user settings for CLI behaviors,
|
|
which apply across all Terraform working directories. This is separate from
|
|
[your infrastructure configuration](/docs/configuration/index.html).
|
|
|
|
## Location
|
|
|
|
The configuration is placed in a single file whose location depends on the
|
|
host operating system:
|
|
|
|
* On Windows, the file must be named named `terraform.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.
|
|
* On all other systems, the file must be named `.terraformrc` (note
|
|
the leading period) and placed directly in the home directory
|
|
of the relevant user.
|
|
|
|
On Windows, beware of Windows Explorer's default behavior of hiding filename
|
|
extensions. Terraform will not recognize a file named `terraform.rc.txt` as a
|
|
CLI configuration file, even though Windows Explorer may _display_ its name
|
|
as just `terraform.rc`. Use `dir` from PowerShell or Command Prompt to
|
|
confirm the filename.
|
|
|
|
The location of the Terraform CLI configuration file can also be specified
|
|
using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/commands/environment-variables.html).
|
|
|
|
## Configuration File Syntax
|
|
|
|
The configuration file uses the same _HCL_ syntax as `.tf` 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"
|
|
disable_checkpoint = true
|
|
```
|
|
|
|
## Available Settings
|
|
|
|
The following settings can be set in the CLI configuration file:
|
|
|
|
- `disable_checkpoint` — when set to `true`, disables
|
|
[upgrade and security bulletin checks](/docs/commands/index.html#upgrade-and-security-bulletin-checks)
|
|
that require reaching out to HashiCorp-provided network services.
|
|
|
|
- `disable_checkpoint_signature` — when set to `true`, allows the upgrade and
|
|
security bulletin checks described above but disables the use of an anonymous
|
|
id used to de-duplicate warning messages.
|
|
|
|
- `plugin_cache_dir` — enables
|
|
[plugin caching](/docs/configuration/providers.html#provider-plugin-cache)
|
|
and specifies, as a string, the location of the plugin cache directory.
|
|
|
|
- `credentials` - configures credentials for use with Terraform Cloud or
|
|
Terraform Enterprise. See [Credentials](#credentials) below for more
|
|
information.
|
|
|
|
- `credentials_helper` - configures an external helper program for the storage
|
|
and retrieval of credentials for Terraform Cloud or Terraform Enterprise.
|
|
See [Credentials Helpers](#credentials-helpers) below for more information.
|
|
|
|
## Credentials
|
|
|
|
[Terraform Cloud](/docs/cloud/index.html) provides a number of remote network
|
|
services for use with Terraform, and
|
|
[Terraform Enterprise](/docs/enterprise/index.html) allows hosting those
|
|
services inside your own infrastructure. For example, these systems offer both
|
|
[remote operations](/docs/cloud/run/cli.html) and a
|
|
[private module registry](/docs/cloud/registry/index.html).
|
|
|
|
When interacting with Terraform-specific network services, Terraform expects
|
|
to find API tokens in CLI configuration files in `credentials` blocks:
|
|
|
|
```hcl
|
|
credentials "app.terraform.io" {
|
|
token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
|
|
}
|
|
```
|
|
|
|
You can have multiple `credentials` blocks if you regularly use services from
|
|
multiple hosts. Many users will configure only one, for either
|
|
Terraform Cloud (at `app.terraform.io`) or for their organization's own
|
|
Terraform Enterprise host. Each `credentials` block contains a `token` argument
|
|
giving the API token to use for that host.
|
|
|
|
~> **Important:** If you are using Terraform Cloud or Terraform Enterprise,
|
|
the token provided must be either a
|
|
[user token](/docs/cloud/users-teams-organizations/users.html#api-tokens)
|
|
or a
|
|
[team token](/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens);
|
|
organization tokens cannot be used for command-line Terraform actions.
|
|
|
|
-> **Note:** The credentials hostname must match the hostname in your module
|
|
sources and/or backend configuration. If your Terraform Enterprise instance
|
|
is available at multiple hostnames, use only one of them consistently.
|
|
Terraform Cloud responds to API calls at both its current hostname
|
|
`app.terraform.io`, and its historical hostname `atlas.hashicorp.com`.
|
|
|
|
If you are running the Terraform CLI interactively on a computer that is capable
|
|
of also running a web browser, you can optionally obtain credentials and save
|
|
them in the CLI configuration automatically using
|
|
[the `terraform login` command](./login.html).
|
|
|
|
### Credentials Helpers
|
|
|
|
If you would prefer not to store your API tokens directly in the CLI
|
|
configuration as described in the previous section, you can optionally instruct
|
|
Terraform to use a different credentials storage mechanism by configuring a
|
|
special kind of plugin program called a _credentials helper_.
|
|
|
|
```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.
|
|
|
|
Terraform 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](/docs/internals/credentials-helpers.html).
|
|
|
|
## Deprecated Settings
|
|
|
|
The following settings are supported for backward compatibility but are no
|
|
longer recommended for use:
|
|
|
|
* `providers` - a configuration block that allows specifying the locations of
|
|
specific plugins for each named provider. This mechanism is deprecated
|
|
because it is unable to specify a version number for each plugin, and thus
|
|
it does not co-operate with the plugin versioning mechanism. Instead,
|
|
place the plugin executable files in
|
|
[the third-party plugins directory](/docs/configuration/providers.html#third-party-plugins).
|