README
¶
tfctl: The HCP Terraform CLI
Comprehensive, official CLI access to the HCP Terraform / Terraform Enterprise platform.
The tfctl CLI provides high-level commands for common workflows, such as managing runs, variables, and workspaces, and direct API access for advanced automation. It supports multiple configuration profiles, allowing you to switch between different HCP Terraform organizations and Terraform Enterprise instances. It also integrates with AI coding agents to facilitate agent-assisted management of Terraform workflows.
Installation
You can install the CLI, command completion utility, and agent skill separately.
Homebrew
MacOS and Linux users can install tfctl from the HashiCorp brew tap:
$ brew install hashicorp/tap/tfctl
Precompiled Binaries
You can download official release binaries at releases.hashicorp.com
Building from Source
See Developers below for details.
Install shell completion
We recommend installing the shell completion module for command, argument, and API path completion.
$ tfctl --autocomplete-install
You can uninstall shell completion with the tfctl --autocomplete-uninstall command.
Install AI agent skill
The tfctl CLI ships with an agent skill that gives AI coding agents access to HCP Terraform through the tfctl command, but discourages non-human delete operations. You can install it using the tfctl harness install command or NPX. Replace <agent> with one of the following supported AI agents:
ampantigravitybobclaudecodexcopilotopencodepi
To install the skill with tfctl harness install command, run:
$ tfctl harness install <agent> --global
To install the skill for other agents using npx skills, run:
$ npx skills add hashicorp/tfctl-cli --skill 'tfctl'
This adds the skill to your user profile so that compatible agents can use tfctl commands on your behalf.
Configure tfctl
The tfctl CLI uses a layered configuration system. You can configure settings in profiles, environment variables, or local Terraform configuration, in order of precedence.
Set hostname
The default hostname is 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 hostname command and specify the hostname you want the CLI to connect to.
$ tfctl profile set hostname <host>
Set authentication token
Run the tfctl auth login command to create and install a token for tfctl to use to authenticate with HCP Terraform or Terraform Enterprise. If you already have a token, you can use tfctl profile set token $TOKEN.
$ tfctl auth login
The command opens HCP Terraform or your Terraform Enterprise instance in a browser window. Click the Create an API token button, then give your token a description and set its expiration. Click Generate token, then copy and paste the new token into your terminal window. The CLI does not print the pasted token to the screen. As with Terraform, tfctl stores these tokens in plain text. Refer to Configuration reference for more information.
Verify that the login is successful before leaving the token page in your browser, because HCP Terraform does not show the token once it's closed. If an issue occurs during the process or you close the dialog showing the token before copying it, you must create a new token.
If the CLI does not find a token configured for the active profile, it checks your Terraform configuration for a matching token. Refer to Terraform tokens for more information.
Set default organization
Run the tfctl profile set default_organization command to set the default organization. Replace <name> with your HCP Terraform or Terraform Enterprise organization name.
$ tfctl profile set default_organization <name>
Example usage
Command Syntax: tfctl <command> [subcommand] [flags] [arguments]
# Scenario: Check the status of two workspaces across two instances of HCP Terraform. Start a run on a workspace.
# Configure profiles for EU and US organizations, and authenticate to both. You must already have users with access to the organizations in each HCP Terraform instance.
$ tfctl profile profiles create us --hostname=app.terraform.io
$ tfctl profile set default_organization my-us-org-name
$ tfctl auth login # Create API token in web browser, copy it, then paste it to terminal
$ tfctl profile profiles create eu --hostname=app.eu.terraform.io
$ tfctl profile set default_organization my-eu-org-name
$ tfctl auth login # Create API token in web browser, copy it, then paste it to terminal
# Get workspace configuration from EU org. Workspace must already exist in this org.
$ tfctl api /organizations/{organization}/workspaces/example-app-workspace
# Get status of last workspace run
$ tfctl run status example-app-workspace
# Switch to US profile
$ tfctl profile profiles activate us
# Start a run on the US workspace. Workspace must already exist in this org.
$ tfctl run start example-app-workspace --message="Run started with tfctl."
# Get detailed run status in JSON format
$ tfctl run status example-app-workspace --json
Manage profiles
Use the tfctl profile profiles command group to create and manage profiles. You can use a different profile for each HCP Terraform organization and each instance of HCP Terraform and instance of Terraform Enterprise.
To create a profile, run the tfctl profile profiles create command and specify a name to create a profile. Replace <name> with a name for your new profile.
$ tfctl profile profiles create <name>
The CLI activates the new profile automatically.
Run tfctl in Docker
If you have a TFCTL_TOKEN environment variable set, you can invoke tfctl using Docker. Refer to Environment variables for more configuration environment variables.
For example, the following command will run tfctl in a docker container, passing the local TFCTL_TOKEN environment variable into the container:
$ docker run -e TFCTL_TOKEN hashicorp/tfctl
Configuration reference
The tfctl CLI stores its configuration in the following directories, depending on your operating system:
- Linux/MacOS:
~/.config/tfctl - Windows:
%AppData%/tfctl
The CLI stores configuration for individual profiles in the profiles subdirectory. For example, profiles/default.hcl stores the configuration for your default profile.
Terraform tokens
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. These tokens may either be in your Terraform configuration directory, for example ~/.terraform.d/credentials.tfrc.json, or the corresponding Terraform environment variables, such as TF_TOKEN_app_terraform_io.
Profile Environment variables
If you have not configured a particular option for the active profile, tfctl checks the following environment variables:
TFCTL_ORGANIZATION: The organization to use for commands that require an organization.
TFCTL_HOSTNAME: The Terraform Enterprise or HCP Terraform hostname to use. Defaults to app.terraform.io.
TFCTL_TOKEN: An HCP Terraform API token to use in conjunction with the default profile. This variable is not used in conjunction with any other profile.
TFCTL_TOKEN_<profile>: An HCP Terraform API token to use in conjunction with the named profile.
TF_TOKEN_<hostname>: An HCP Terraform API token to present during authentication, with the specified hostname in Punycode formatting, for example TF_TOKEN_app_terraform_io. The CLI present the Terraform token only if it has not been configured in any other way.
Behavior Environment Variables
TFCTL_CONFIG_DIR: Change the location of the tfctl config directory, which is ~/.config/tfctl by default.
TFCTL_SKIP_MIGRATE: Don't migrate installed skill files to the latest version (if contents are known to be installed by a previous version).
CHECKPOINT_DISABLE: Don't check for newer versions of tfctl.
Command reference
The tfctl command can manage HCP Terraform runs and variables with the corresponding subcommands. It also provides direct access to the HCP Terraform API with the api subcommand.
Global flags
tfctl supports the following global flags.
-
--help: Detailed usage instructions for any command. -
--debug: Enable debug output. -
--dry-run: Creates a preview of the proposed changes without making them. -
--json: Sets the output format to JSON. -
--jq=<expression>: A jq filter expression to apply to JSON output. Implies--json -
--markdown: Sets the output format to Markdown -
--no-color: Disables color output. -
--profile=<name>: The profile to use. If omitted, the CLI uses the current profile. -
--quiet: Minimizes output, rendering only essential content. -
--version: Print the version oftfctlCLI.
Exit Codes
| Exit | Meaning | Solution |
|---|---|---|
| 0 | OK | — |
| 1 | Usage error | Read tfctl <cmd> --help |
| 2 | Not Found or Authorization Error | Verify URL/ID |
| 3 | Authentication Error | tfctl auth login |
| 4 | Network error | Check connectivity |
| 5 | API Server Error Persists | Try again later |
| 6 | Underlying error detected | Varies depending on error condition |
| 130 | Canceled (ctrl-c). | — |
Telemetry
By default, HashiCorp collects anonymous, redacted trace telemetry for each command invocation, including the command name, exit status, network metrics, and basic process information. You can disable telemetry using any of these methods: Set TFCTL_TELEMETRY to disabled, Set DO_NOT_TRACK to true, or set telemetry to disabled in your profile:
$ tfctl profile set telemetry disabled
You can view the telemetry that we transmit by setting profile telemetry to log:
$ tfctl profile set telemetry log
See TELEMETRY.md for more information, including full trace schema.
Uninstall/Clean up
Uninstall Shell Completions
$ tfctl --autocomplete-uninstall
Developers
Installing from Source
Prerequisites
- go v1.26.4 or later
- git
- make
Install tfctl
- Clone the git repository:
- SSH:
git clone git@github.com:hashicorp/tfctl-cli.git - HTTPS:
git clone https://github.com/hashicorp/tfctl-cli.git
- SSH:
- Change to the new directory:
cd tfctl-cli - Run
make go/install.
Verify the installation:
$ tfctl --version
Developers
See CONTRIBUTING.md for information about developing tfctl.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tfctl
command
Package main provides the tfctl CLI entrypoint.
|
Package main provides the tfctl CLI entrypoint. |
|
internal
|
|
|
commands/api
Package api implements the tfctl CLI API command.
|
Package api implements the tfctl CLI API command. |
|
commands/auth
Package auth implements the `auth` command group for managing authentication.
|
Package auth implements the `auth` command group for managing authentication. |
|
commands/cmdtest
Package cmdtest provides shared test helpers for command tests.
|
Package cmdtest provides shared test helpers for command tests. |
|
commands/cmdutil
Package cmdutil provides shared helpers for command implementations.
|
Package cmdutil provides shared helpers for command implementations. |
|
commands/create
Package create implements the tfctl create command.
|
Package create implements the tfctl create command. |
|
commands/get
Package get implements the tfctl get command.
|
Package get implements the tfctl get command. |
|
commands/harness
Package harness implements the `harness` command group.
|
Package harness implements the `harness` command group. |
|
commands/profile
Package profile implements the `profile` command group for managing configuration profiles
|
Package profile implements the `profile` command group for managing configuration profiles |
|
commands/profile/profiles
Package profiles implements the `profile profiles` command group for managing configuration profiles.
|
Package profiles implements the `profile profiles` command group for managing configuration profiles. |
|
commands/root
Package root implements the root command for the CLI.
|
Package root implements the root command for the CLI. |
|
commands/run
Package run implements the `run` command group.
|
Package run implements the `run` command group. |
|
commands/variable
Package variable implements the `variable` command group.
|
Package variable implements the `variable` command group. |
|
commands/versioncmd
Package versioncmd provides the hidden version command for the tfctl CLI, which is invoked using `--version`, `-v`, or `version`
|
Package versioncmd provides the hidden version command for the tfctl CLI, which is invoked using `--version`, `-v`, or `version` |
|
pkg/checkpoint
Package checkpoint provides functionality for interacting with HashiCorp's Checkpoint service to check for new versions and alerts related to the current version of the CLI.
|
Package checkpoint provides functionality for interacting with HashiCorp's Checkpoint service to check for new versions and alerts related to the current version of the CLI. |
|
pkg/client
Package client provides configured HCP Terraform API clients and raw request helpers.
|
Package client provides configured HCP Terraform API clients and raw request helpers. |
|
pkg/cmd
Package cmd provides the structures and functions for constructing commands.
|
Package cmd provides the structures and functions for constructing commands. |
|
pkg/execsession
Package execsession manages short-lived, process-scoped permission grants that allow nested tfctl invocations to perform noninteractive deletes.
|
Package execsession manages short-lived, process-scoped permission grants that allow nested tfctl invocations to perform noninteractive deletes. |
|
pkg/flagvalue
Package flagvalue provides custom pflag.Value implementations for common flag types.
|
Package flagvalue provides custom pflag.Value implementations for common flag types. |
|
pkg/format
Package format provides utilities for handling output formats.
|
Package format provides utilities for handling output formats. |
|
pkg/git
Package git inspects the current repository and parses git remote metadata.
|
Package git inspects the current repository and parses git remote metadata. |
|
pkg/heredoc
Package heredoc provides utilities for formatting text that is intended to be output to users and includes text/template formatting and word-wrapping.
|
Package heredoc provides utilities for formatting text that is intended to be output to users and includes text/template formatting and word-wrapping. |
|
pkg/inputguard
Package inputguard provides lightweight input-hygiene checks for user-supplied CLI values.
|
Package inputguard provides lightweight input-hygiene checks for user-supplied CLI values. |
|
pkg/iostreams
Package iostreams provides access to the terminal outputs and inputs in a centralized and mockable fashion.
|
Package iostreams provides access to the terminal outputs and inputs in a centralized and mockable fashion. |
|
pkg/ld
Package ld implements levenshtein distance in order to provide suggestions based on similarity.
|
Package ld implements levenshtein distance in order to provide suggestions based on similarity. |
|
pkg/logging
Package logging provides utilities for creating and accessing a logger within the application.
|
Package logging provides utilities for creating and accessing a logger within the application. |
|
pkg/openapi
Package openapi loads and provides access to the embedded OpenAPI specification for API v2.
|
Package openapi loads and provides access to the embedded OpenAPI specification for API v2. |
|
pkg/profile
Package profile stores the CLI configuration for the named profile.
|
Package profile stores the CLI configuration for the named profile. |
|
pkg/resource
Package resource provides a registry of known HCP Terraform API resource types.
|
Package resource provides a registry of known HCP Terraform API resource types. |
|
pkg/table
Package table outputs data in a table format.
|
Package table outputs data in a table format. |
|
pkg/telemetry
Package telemetry provides OpenTelemetry tracing for the tfctl CLI.
|
Package telemetry provides OpenTelemetry tracing for the tfctl CLI. |
|
pkg/terraform
Package terraform reads local Terraform configuration and tfvars inputs.
|
Package terraform reads local Terraform configuration and tfvars inputs. |
|
Package skills contains the embedded skill definitions for tfctl.
|
Package skills contains the embedded skill definitions for tfctl. |
|
Package version contains build time configuration for the CLI, such as version information.
|
Package version contains build time configuration for the CLI, such as version information. |