Manage tfctl profiles

This topic describes how to create and manage tfctl profiles. Profiles store configuration settings such as authentication tokens, default organizations, and hostnames, allowing you to work with multiple organizations and instances of HCP Terraform and Terraform Enterprise without reconfiguring tfctl each time you switch contexts.

Background

When you begin using tfctl, it creates a default profile that stores your authentication token and configuration settings. When you want to manage multiple organizations or work across different instances of HCP Terraform and Terraform Enterprise, you can create additional profiles. Each profile maintains its own settings, including:

Authentication token
Default organization
Hostname of your HCP Terraform or Terraform Enterprise instance
Configuration preferences such as output color

Use profiles to manage multiple organizations within the same HCP Terraform or Terraform Enterprise instance, work across different instances of HCP Terraform or Terraform Enterprise, and maintain separate configurations for different teams or projects.

Requirements

Before managing profiles, ensure you have:

tfctl installed on your system. Refer to Install tfctl for instructions.
A user account with permissions to manage your organization in the HCP Terraform or Terraform Enterprise instance. Refer to Permissions overview to learn more.

Profile configuration

tfctl stores configuration settings for each profile. You can also configure tfctl with environment variables. Profile configuration settings take precedence over environment variables. Refer to Environment variables for more details about environment variables.

The default profile

When you start using tfctl, it creates and activates your default profile. Use the tfctl profile commands to get, set, and display your profile's settings.

Create a profile

Complete the following steps to create a new profile:

Create the profile using the tfctl profile profiles create command. Replace <PROFILE_NAME> with a descriptive name for your profile:
```
$ tfctl profile profiles create <PROFILE_NAME>
```
The command creates the profile and automatically activates it.
Configure the profile's hostname if you are using Terraform Enterprise or a different HCP Terraform instance. Replace <HOSTNAME> with your instance hostname:
```
$ tfctl profile set hostname <HOSTNAME>
```
If you are using the default HCP Terraform instance at app.terraform.io, you can skip this step.
Authenticate the profile:
```
$ tfctl auth login
```
The command opens your browser to generate an authentication token. Refer to Authenticate tfctl for detailed authentication instructions.
Set the default organization for the profile. Replace <ORGANIZATION_NAME> with your organization name:
```
$ tfctl profile set default_organization <ORGANIZATION_NAME>
```
Verify the profile configuration:
```
$ tfctl profile display
```
The command displays all settings for the active profile.

Switch between profiles

Use the tfctl profile profiles activate command to switch to a different profile. Replace <PROFILE_NAME> with the name of the profile you want to activate:

$ tfctl profile profiles activate <PROFILE_NAME>

After activating a profile, all subsequent tfctl commands use that profile's settings until you activate a different profile.

Use a profile for a single command

To run a single command with a different profile without changing your active profile, use the --profile global flag. Replace <PROFILE_NAME> with the profile name and <COMMAND> with your tfctl command:

$ tfctl --profile <PROFILE_NAME> <COMMAND>

For example, to list workspaces using your production profile while keeping your development profile active:

$ tfctl --profile production get workspaces

List profiles

Use the tfctl profile profiles list command to view all configured profiles:

$ tfctl profile profiles list

The command displays each profile's name, hostname, default organization, and indicates which profile is currently active.

Modify profile settings

Use the tfctl profile set command to modify settings for the active profile. The following examples demonstrate common configuration changes:

Change the default organization

$ tfctl profile set default_organization <NEW_ORGANIZATION>

Change the hostname

$ tfctl profile set hostname <NEW_HOSTNAME>

Disable color output

$ tfctl profile set no_color true

Configure telemetry

$ tfctl profile set telemetry disabled

Refer to the tfctl profile command reference for a complete list of available properties.

Delete a profile

Use the tfctl profile profiles delete command to remove a profile you no longer need. Replace <PROFILE_NAME> with the profile name:

$ tfctl profile profiles delete <PROFILE_NAME>

You cannot delete the currently active profile. Activate a different profile before deleting the one you want to remove.

Environment variable overrides

Environment variables can override profile settings for individual command executions. This is useful for CI/CD pipelines or temporary configuration changes. The following environment variables are available:

TFCTL_ORGANIZATION: Override the default organization
TFCTL_HOSTNAME: Override the hostname
TFCTL_TOKEN: Override the authentication token for the default profile
TFCTL_TOKEN_<profile>: Override the authentication token for a named profile

Profile configuration flags take precedence over environment variables. Refer to Configuration for more details about environment variables.

Next steps

After configuring your profiles, you can:

Review examples for common tfctl workflows
Integrate with AI agents
Read the CLI reference documentation