HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform Home

tfctl CLI command reference

This topic provides an overview of all tfctl CLI commands. Each command reference includes documentation with usage examples, arguments, and options.

The tfctl CLI provides three levels of abstraction for interacting with HCP Terraform and Terraform Enterprise:

  • High-level commands, such as tfctl get workspaces and tfctl run start, for common operations
  • Generic commands, such as tfctl create and tfctl get, that work with any resource type
  • Direct API access using the tfctl api command group for operations not covered by convenience commands

This reference documents all available commands, their options, and usage patterns.

Command categories

The tfctl command includes subgroups for different operations.

Top-level commands

The create and get commands allow you to create and get HCP Terraform resources.

Authentication

The tfctl auth command group allows you to authenticate tfctl with HCP Terraform or Terraform Enterprise.

Harness management

The tfctl harness command group allows you to manage AI agent harness contexts.

Profile configuration

The tfctl profile command group allows you to manage configuration profiles to support multiple organizations and instances of HCP Terraform and Terraform Enterprise.

Run management

The tfctl run command group allows you to manage Terraform runs on your workspaces.

Variable management

The tfctl variable command group allows you to manage variables in workspaces and variable sets.

API operations

The tfctl api command group supports full access to HCP Terraform's API.

Global flags

All tfctl commands support global flags that control CLI behavior, output formatting, and execution mode. For detailed information about each flag, including data types and examples, refer to the Global flags reference.

Pagination

Commands that list resources, such as tfctl get and tfctl api, support pagination options to control how results are returned.

Pagination options

Operations that paginate their output support the following flags:

  • --page-size=NUMBER: Number of results per page. The default varies by resource type and is determined by the API.
  • --page-number=NUMBER: Page number to fetch. Page numbers begin at 1. Defaults to 1.
  • --all: Automatically fetch all pages. When using --all, the command fetches the first page, follows pagination links in the response, and continues until all pages are retrieved. Limited to 2000 records maximum.

Behavior

By default, commands return a single page of results with an API-determined page size. Use --page-size to control how many records per page, and --page-number to fetch a specific page.

When you use the --all flag, tfctl fetches all available pages sequentially until it reaches 2000 records or no more results remain, whichever comes first. Note that --page-size and --page-number are ignored when --all is set.

Examples

List workspaces with custom page size:

$ tfctl get workspaces --page-size 50

Fetch a specific page:

$ tfctl get workspaces --page-number 2

Automatically fetch all pages:

$ tfctl get workspaces --all

Exit codes

The tfctl CLI uses the following exit codes:

Exit codeDescriptionSolution
0Success—
1Usage errorRead tfctl <cmd> --help
2HCP Terraform not found or authorization errorVerify URL or your ID
3API authorization errorRun tfctl auth login
4Network errorCheck connectivity
5API server error persistsTry again later
6Underlying error detectedVaries depending on error condition, for example, run tfctl auth status when not authenticated
130Canceled (Ctrl-C)—

Related

Edit this page on GitHub