Authenticate tfctl with HCP Terraform and Terraform Enterprise

This topic describes how to authenticate tfctl with HCP Terraform or Terraform Enterprise. You must authenticate tfctl with your HCP Terraform or Terraform Enterprise account before you can use it to manage Terraform runs, variables, and other resources.

Requirements

Before authenticating, ensure you have:

tfctl installed on your system. Refer to Install tfctl for detailed instructions.
An HCP Terraform or Terraform Enterprise account.

Set hostname

By default, tfctl connects to the HCP Terraform instance at app.terraform.io. To use a different HCP Terraform instance or your organization's Terraform Enterprise instance, use the tfctl profile set command to replace <HOSTNAME> with your HCP Terraform or Terraform Enterprise hostname.

$ tfctl profile set hostname <HOSTNAME>

Authenticate

Complete the following steps to authenticate tfctl with HCP Terraform or Terraform Enterprise:

Run the login command:
```
$ tfctl auth login
```
The command first prompts you to confirm you want to proceed. Respond with a y.
Next, the command opens your default web browser to create a user token for tfctl for your HCP Terraform or Terraform Enterprise organization.
In your browser, give your token a description and set its expiration, then click the Generate token button.
After you create your token, copy it to your clipboard. HCP Terraform and Terraform Enterprise do not display your token again.
Return to your terminal and paste the token. The CLI does not print the pasted token to the screen.
Verify your authentication status:
```
$ tfctl auth status
```
The command verifies that your token is valid and displays your authentication status and the associated username.

Authentication token storage

The tfctl CLI stores authentication tokens in plain text in your configuration directory. For details on configuration directory locations, refer to Configuration.

Reuse Terraform CLI tokens

If you have already authenticated the Terraform CLI against your HCP Terraform or Terraform Enterprise user, tfctl can reuse your existing authentication tokens. This means you don't need to create a separate token for tfctl.

If you have not configured a token for the active profile with tfctl auth login, the tfctl CLI checks your Terraform configuration for a matching token. Terraform may have stored matching tokens in either your Terraform configuration directory, for example ~/.terraform.d/credentials.tfrc.json, or the corresponding Terraform environment variables, such as TF_TOKEN_app_terraform_io.

Next steps

After authenticating tfctl, you can: