github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/commands/cli-config.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "CLI Configuration"
     4  sidebar_current: "docs-commands-cli-config"
     5  description: |-
     6    The general behavior of the Terraform CLI can be customized using the CLI
     7    configuration file.
     8  ---
     9  
    10  # CLI Configuration File (`.terraformrc` or `terraform.rc`)
    11  
    12  The CLI configuration file configures per-user settings for CLI behaviors,
    13  which apply across all Terraform working directories. This is separate from
    14  [your infrastructure configuration](/docs/configuration/index.html).
    15  
    16  ## Location
    17  
    18  The configuration is placed in a single file whose location depends on the
    19  host operating system:
    20  
    21  * On Windows, the file must be named named `terraform.rc` and placed
    22    in the relevant user's `%APPDATA%` directory. The physical location
    23    of this directory depends on your Windows version and system configuration;
    24    use `$env:APPDATA` in PowerShell to find its location on your system.
    25  * On all other systems, the file must be named `.terraformrc` (note
    26    the leading period) and placed directly in the home directory
    27    of the relevant user.
    28  
    29  On Windows, beware of Windows Explorer's default behavior of hiding filename
    30  extensions. Terraform will not recognize a file named `terraform.rc.txt` as a
    31  CLI configuration file, even though Windows Explorer may _display_ its name
    32  as just `terraform.rc`. Use `dir` from PowerShell or Command Prompt to
    33  confirm the filename.
    34  
    35  The location of the Terraform CLI configuration file can also be specified
    36  using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/commands/environment-variables.html).
    37  
    38  ## Configuration File Syntax
    39  
    40  The configuration file uses the same _HCL_ syntax as `.tf` files, but with
    41  different attributes and blocks. The following example illustrates the
    42  general syntax; see the following section for information on the meaning
    43  of each of these settings:
    44  
    45  ```hcl
    46  plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
    47  disable_checkpoint = true
    48  ```
    49  
    50  ## Available Settings
    51  
    52  The following settings can be set in the CLI configuration file:
    53  
    54  - `disable_checkpoint` — when set to `true`, disables
    55    [upgrade and security bulletin checks](/docs/commands/index.html#upgrade-and-security-bulletin-checks)
    56    that require reaching out to HashiCorp-provided network services.
    57  
    58  - `disable_checkpoint_signature` — when set to `true`, allows the upgrade and
    59    security bulletin checks described above but disables the use of an anonymous
    60    id used to de-duplicate warning messages.
    61  
    62  - `plugin_cache_dir` — enables
    63    [plugin caching](/docs/configuration/providers.html#provider-plugin-cache)
    64    and specifies, as a string, the location of the plugin cache directory.
    65  
    66  - `credentials` - configures credentials for use with Terraform Cloud or
    67    Terraform Enterprise. See [Credentials](#credentials) below for more
    68    information.
    69  
    70  - `credentials_helper` - configures an external helper program for the storage
    71    and retrieval of credentials for Terraform Cloud or Terraform Enterprise.
    72    See [Credentials Helpers](#credentials-helpers) below for more information.
    73  
    74  ## Credentials
    75  
    76  [Terraform Cloud](/docs/cloud/index.html) provides a number of remote network
    77  services for use with Terraform, and
    78  [Terraform Enterprise](/docs/enterprise/index.html) allows hosting those
    79  services inside your own infrastructure. For example, these systems offer both
    80  [remote operations](/docs/cloud/run/cli.html) and a
    81  [private module registry](/docs/cloud/registry/index.html).
    82  
    83  When interacting with Terraform-specific network services, Terraform expects
    84  to find API tokens in CLI configuration files in `credentials` blocks:
    85  
    86  ```hcl
    87  credentials "app.terraform.io" {
    88    token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
    89  }
    90  ```
    91  
    92  You can have multiple `credentials` blocks if you regularly use services from
    93  multiple hosts. Many users will configure only one, for either
    94  Terraform Cloud (at `app.terraform.io`) or for their organization's own
    95  Terraform Enterprise host. Each `credentials` block contains a `token` argument
    96  giving the API token to use for that host.
    97  
    98  ~> **Important:** If you are using Terraform Cloud or Terraform Enterprise,
    99  the token provided must be either a
   100  [user token](/docs/cloud/users-teams-organizations/users.html#api-tokens)
   101  or a
   102  [team token](/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens);
   103  organization tokens cannot be used for command-line Terraform actions.
   104  
   105  -> **Note:** The credentials hostname must match the hostname in your module
   106  sources and/or backend configuration. If your Terraform Enterprise instance
   107  is available at multiple hostnames, use only one of them consistently.
   108  Terraform Cloud responds to API calls at both its current hostname
   109  `app.terraform.io`, and its historical hostname `atlas.hashicorp.com`.
   110  
   111  If you are running the Terraform CLI interactively on a computer that is capable
   112  of also running a web browser, you can optionally obtain credentials and save
   113  them in the CLI configuration automatically using
   114  [the `terraform login` command](./login.html).
   115  
   116  ### Credentials Helpers
   117  
   118  If you would prefer not to store your API tokens directly in the CLI
   119  configuration as described in the previous section, you can optionally instruct
   120  Terraform to use a different credentials storage mechanism by configuring a
   121  special kind of plugin program called a _credentials helper_.
   122  
   123  ```hcl
   124  credentials_helper "example" {
   125    args = []
   126  }
   127  ```
   128  
   129  `credentials_helper` is a configuration block that can appear at most once
   130  in the CLI configuration. Its label (`"example"` above) is the name of the
   131  credentials helper to use. The `args` argument is optional and allows passing
   132  additional arguments to the helper program, for example if it needs to be
   133  configured with the address of a remote host to access for credentials.
   134  
   135  A configured credentials helper will be consulted only to retrieve credentials
   136  for hosts that are _not_ explicitly configured in a `credentials` block as
   137  described in the previous section.
   138  Conversely, this means you can override the credentials returned by the helper
   139  for a specific hostname by writing a `credentials` block alongside the
   140  `credentials_helper` block.
   141  
   142  Terraform does not include any credentials helpers in the main distribution.
   143  To learn how to write and install your own credentials helpers to integrate
   144  with existing in-house credentials management systems, see
   145  [the guide to Credentials Helper internals](/docs/internals/credentials-helpers.html).
   146  
   147  ## Deprecated Settings
   148  
   149  The following settings are supported for backward compatibility but are no
   150  longer recommended for use:
   151  
   152  * `providers` - a configuration block that allows specifying the locations of
   153    specific plugins for each named provider. This mechanism is deprecated
   154    because it is unable to specify a version number for each plugin, and thus
   155    it does not co-operate with the plugin versioning mechanism. Instead,
   156    place the plugin executable files in
   157    [the third-party plugins directory](/docs/configuration/providers.html#third-party-plugins).