HashiCorp 发布 HCP Terraform 官方 CLI 工具 tfctl

全面、官方的 HCP Terraform / Terraform Enterprise 平台 CLI 访问。

tfctl CLI 为常见工作流提供高级命令，例如管理运行、变量和工作区，并为高级自动化提供直接 API 访问。它支持多个配置配置文件，允许您在不同的 HCP Terraform 组织和 Terraform Enterprise 实例之间切换。它还与 AI 编码代理集成，以促进代理辅助的 Terraform 工作流管理。

安装

您可以分别安装 CLI、命令补全实用程序和代理技能。

Homebrew

MacOS 和 Linux 用户可以从 HashiCorp brew tap 安装 tfctl：

$ brew install hashicorp/tap/tfctl

预编译二进制文件

您可以在 releases.hashicorp.com 下载官方发布二进制文件

从源代码构建

有关详细信息，请参阅下方的 开发者。

安装 shell 补全

我们建议安装 shell 补全模块，以实现命令、参数和 API 路径补全。

$ tfctl --autocomplete-install

您可以使用 tfctl --autocomplete-uninstall 命令卸载 shell 补全。

安装 AI 代理技能

tfctl CLI 附带一个代理技能，使 AI 编码代理能够通过 tfctl 命令访问 HCP Terraform，但不鼓励非人类删除操作。您可以使用 tfctl harness install 命令或 NPX 安装它。将 <agent> 替换为以下支持的 AI 代理之一：

• amp
• antigravity
• bob
• claude
• codex
• copilot
• opencode
• pi

要使用 tfctl harness install 命令安装技能，请运行：

$ tfctl harness install <agent> --global

要使用 npx skills 为其他代理安装技能，请运行：

$ npx skills add hashicorp/tfctl-cli --skill 'tfctl'

这会将技能添加到您的用户配置文件中，以便兼容的代理可以代表您使用 tfctl 命令。

配置 tfctl

tfctl CLI 使用分层配置系统。您可以按优先级顺序在配置文件、环境变量或本地 Terraform 配置中配置设置。

设置主机名

默认主机名是位于 app.terraform.io 的 HCP Terraform 实例。要使用不同的 HCP Terraform 实例或您组织的 Terraform Enterprise 实例，请使用 tfctl profile set hostname 命令并指定您希望 CLI 连接的主机名。

$ tfctl profile set hostname <host>

设置身份验证令牌

运行 tfctl auth login 命令以创建并安装一个令牌，供 tfctl 用于向 HCP Terraform 或 Terraform Enterprise 进行身份验证。如果您已有令牌，可以使用 tfctl profile set token $TOKEN。

$ tfctl auth login

该命令会在浏览器窗口中打开 HCP Terraform 或您的 Terraform Enterprise 实例。点击 Create an API token 按钮，然后为您的令牌添加描述并设置其过期时间。点击 Generate token，然后将新令牌复制并粘贴到您的终端窗口中。CLI 不会将粘贴的令牌打印到屏幕上。与 Terraform 一样，tfctl 以明文形式存储这些令牌。有关更多信息，请参阅 配置参考。

在离开浏览器中的令牌页面之前，请验证登录是否成功，因为 HCP Terraform 在关闭后不会再次显示令牌。如果在此过程中出现问题，或者您在复制令牌之前关闭了显示令牌的对话框，则必须创建一个新令牌。

如果 CLI 未找到为活动配置文件配置的令牌，它会检查您的 Terraform 配置中是否有匹配的令牌。有关更多信息，请参阅 Terraform 令牌。

设置默认组织

运行 tfctl profile set default_organization 命令以设置默认组织。将 <name> 替换为您的 HCP Terraform 或 Terraform Enterprise 组织名称。

$ tfctl profile set default_organization <name>

示例用法

命令语法： 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

管理配置文件

使用 tfctl profile profiles 命令组来创建和管理配置文件。你可以为每个 HCP Terraform 组织、每个 HCP Terraform 实例以及每个 Terraform Enterprise 实例使用不同的配置文件。

要创建配置文件，请运行 tfctl profile profiles create 命令并指定一个名称来创建配置文件。将 <name> 替换为你新配置文件的名称。

$ tfctl profile profiles create <name>

CLI 会自动激活新配置文件。

在 Docker 中运行 tfctl

如果你设置了 TFCTL_TOKEN 环境变量，就可以使用 Docker 调用 tfctl。有关更多配置环境变量，请参阅环境变量。

例如，以下命令将在 docker 容器中运行 tfctl，并将本地的 TFCTL_TOKEN 环境变量传入容器：

$ docker run -e TFCTL_TOKEN hashicorp/tfctl

配置参考

tfctl CLI 根据你的操作系统将配置存储在以下目录中：

• Linux/MacOS：~/.config/tfctl
• Windows：%AppData%/tfctl

CLI 将各个配置文件的配置存储在 profiles 子目录中。例如，profiles/default.hcl 存储默认配置文件的配置。

Terraform 令牌

如果你尚未使用 tfctl auth login 为当前活动配置文件配置令牌，tfctl CLI 会检查你的 Terraform 配置中是否有匹配的令牌。这些令牌可能位于你的 Terraform 配置目录中，例如 ~/.terraform.d/credentials.tfrc.json，或者位于相应的 Terraform 环境变量中，例如 TF_TOKEN_app_terraform_io。

配置文件环境变量

如果你没有为当前活动配置文件配置某个特定选项，tfctl 会检查以下环境变量：

TFCTL_ORGANIZATION：用于需要组织的命令的组织。

TFCTL_HOSTNAME：要使用的 Terraform Enterprise 或 HCP Terraform 主机名。默认为 app.terraform.io。

TFCTL_TOKEN：与默认配置文件配合使用的 HCP Terraform API 令牌。此变量不会与任何其他配置文件配合使用。

TFCTL_TOKEN_<profile>：与指定名称的配置文件配合使用的 HCP Terraform API 令牌。

TF_TOKEN_<hostname>：在身份验证期间提供的 HCP Terraform API 令牌，需使用 Punycode 格式的指定主机名，例如 TF_TOKEN_app_terraform_io。CLI 仅在此 Terraform 令牌尚未通过任何其他方式配置时才会提供它。

行为环境变量

TFCTL_CONFIG_DIR：更改 tfctl 配置目录的位置，默认为 ~/.config/tfctl。

TFCTL_SKIP_MIGRATE：不要将已安装的技能文件迁移到最新版本（如果已知内容是由先前版本安装的）。

TFCTL_REDACT：控制输出中敏感值的掩码。接受 strict（默认值）、known 或 off。请参阅输出脱敏。

CHECKPOINT_DISABLE：不要检查 tfctl 的新版本。

命令参考

tfctl 命令可以通过相应的子命令管理 HCP Terraform 运行和变量。它还通过 api 子命令提供对 HCP Terraform API 的直接访问。

全局标志

tfctl 支持以下全局标志。

• --help：任何命令的详细使用说明。

• --debug：启用调试输出。

• --dry-run：创建拟议更改的预览，但不实际进行更改。

• --json：将输出格式设置为 JSON。

• --jq=<expression>：应用于 JSON 输出的 jq 过滤表达式。隐含 --json

• --markdown：将输出格式设置为 Markdown

• --no-color：禁用彩色输出。

• --no-redact：在输出中显示敏感值而不是将其掩码。请参阅输出脱敏。

• --profile=<name>：要使用的配置文件。如果省略，CLI 将使用当前配置文件。

• --quiet：最小化输出，仅呈现必要内容。

• --version：打印 tfctl CLI 的版本。

输出脱敏

有些 API 响应会携带凭据。创建的令牌会完整返回一次，而状态版本会携带签名的下载 URL，这些 URL 授予对状态的访问权限，状态中包含 Terraform 写入的每一个值。tfctl 会在所有输出格式中屏蔽这些值，包括 --json 和 --jq，并报告它屏蔽了哪些字段。屏蔽仅适用于响应正文。它不是访问控制边界：API 决定你的令牌可以读取什么，而脱敏限制了被允许的响应在终端、日志或自动化调用方中留下的内容。

通过 redact 配置文件属性或 TFCTL_REDACT 环境变量设置模式：

• strict（默认）：屏蔽已知的机密字段、API 声明为敏感的值，以及名称或形态表明是凭据的值。

• known：仅屏蔽已知的机密字段和 API 声明为敏感的值。当名称或形态启发式规则隐藏了你需要的值时，请使用此模式。

• off：禁用屏蔽。--no-redact 标志对单个命令执行相同操作。

退出代码

遥测

默认情况下，HashiCorp 会为每次命令调用收集匿名的、经过脱敏的跟踪遥测数据，包括命令名称、退出状态、网络指标和基本进程信息。你可以使用以下任一方法禁用遥测：将 TFCTL_TELEMETRY 设置为 disabled，将 DO_NOT_TRACK 设置为 true，或在配置文件中将遥测设置为 disabled：

$ tfctl profile set telemetry disabled

你可以通过将配置文件中的遥测设置为 log 来查看我们传输的遥测数据：

$ tfctl profile set telemetry log

有关更多信息，包括完整的跟踪架构，请参阅 TELEMETRY.md。

卸载/清理

卸载 Shell 补全

$ tfctl --autocomplete-uninstall

开发者

从源代码安装

先决条件

• go v1.26.4 或更高版本
• git
• make

安装 tfctl

1. Clone the git repository:
   • SSH：git clone git@github.com:hashicorp/tfctl-cli.git
   • HTTPS：git clone https://github.com/hashicorp/tfctl-cli.git
2. 切换到新目录：cd tfctl-cli
3. 运行 make go/install。

验证安装：

$ tfctl --version

开发者

有关开发 tfctl 的信息，请参阅 CONTRIBUTING.md。