tfctl api

The tfctl api command group performs any HCP Terraform or Terraform Enterprise API v2 request. The tfctl api search subcommand searches and inspects API operations.

Usage

$ tfctl api PATH [options]

Description

The tfctl api command performs any HCP Terraform API v2 request. This is a low-level command that provides direct access to the HCP Terraform API, allowing you to make any API call that the HCP Terraform API supports.

For common operations, consider using the higher-level tfctl get and tfctl create commands, which provide a more user-friendly interface.

The tfctl api schema command group includes subcommands to allow you to search and inspect API operations using HCP Terraform's OpenAPI specification.

Arguments

• PATH: API path or URL. Supports {name} path parameter name resolution.
  • Required

Command groups

• schema - Search and inspect API operations

Flags

• --all: Fetch all records. May be slow for large amounts of data. Limited to 2000 records.

  • Optional.
  • Data type: boolean
  • Default value: None

• --attribute=KEY=VALUE, -a=KEY=VALUE: Attribute for JSON:API request bodies. Implies POST method. Can be repeated to set multiple attributes.

  • Optional.
  • Data type: string (repeatable)
  • Default value: None

• --field=KEY=VALUE, -f=KEY=VALUE: Add a query parameter to the request URL. Can be repeated to add multiple query parameters.

  • Optional.
  • Data type: String.
  • Default value: None

• --header='name: value', -H='name: value': Request header. Can be repeated to add multiple headers.

  • Optional.
  • Data type: string (repeatable)
  • Default value: None

• --input=BODY, -i=BODY: Raw JSON request body. Specify - to read from stdin.

  • Optional.
  • Data type: string
  • Default value: None

• --method=METHOD, -X=METHOD: HTTP method to use (for example, GET, POST, PATCH, DELETE).

  • Optional.
  • Data type: string
  • Default value: Inferred from flags

• --page-number=NUMBER, -n=NUMBER: Page number to return. Ignored if --all is set.

  • Optional.
  • Data type: number
  • Default value: 1

• --page-size=SIZE, -s=SIZE: Limit the number of records to return. Default varies by resource. Ignored if --all is set.

  • Optional.
  • Data type: number
  • Default value: Varies by resource

• --pathparam=KEY=VALUE, -p=KEY=VALUE: Provide values for path parameter resolution. The HCP Terraform API typically requires a resource ID when API paths refer to a specific resource. You can pass resource names for workspaces, teams, projects, or variable sets with this flag, which tfctl will automatically resolve to the resource ID. Can be repeated to set multiple path parameters.

  • Optional if the active profile provides a value for all path parameters, for example {organization}.
  • Data type: string
  • Default value: Auto-resolved from profile or configuration

• --type=TYPE, -t=TYPE: Resource type for --attribute JSON:API request bodies. This value is inferred from the path whenever possible.

  • Optional.
  • Data type: string
  • Default value: Inferred from path

Pagination

Commands that list multiple resources are paginated. For details on pagination options and behavior, refer to Pagination.

Global flags

Refer to Global flags reference for information about flags you can use with all commands.

Path parameter resolution

Use {name} placeholders for path parameters and --pathparam to set their values:

$ tfctl api /workspaces/{workspace}/runs -p workspace=my-workspace

Automatic parameter value resolution

If you do not provide a value for certain path parameters, tfctl automatically determines them from your configuration:

• {organization}: Uses the active profile's default_organization property, or falls back to the local Terraform configuration's organization, if any
• {workspace}: Uses the local Terraform configuration's workspace name, if any

Name-to-ID resolution

When you provide a resource name instead of an ID for certain path parameters, tfctl automatically looks up and uses the corresponding ID. This applies to:

• {workspace}: Workspace name resolves to a workspace ID, with the ws- prefix.
• {team}: Team name resolves to team ID, with the team- prefix.
• {project}: Project name resolves to project ID, with the prj- prefix.
• {varset}: Variable set name resolves to variable set ID, with the varset- prefix.

Examples

The following examples demonstrate how to make direct API calls to HCP Terraform or Terraform Enterprise.

Discovering API operations

Before making API calls, use the tfctl api schema commands to discover available operations. The following examples show how to search for and inspect API operations.

Search for operations

Search for workspace-related operations.

$ tfctl api schema search workspace

Get operation details

View the schema for a specific operation by operation ID.

$ tfctl api schema get getWorkspace

Read resources

List and display information about individual resources by specifying the path along with any required parameters.

List workspaces in the active profile's organization

List all workspaces in the organization configured for your active profile:

$ tfctl api /organizations/{organization}/workspaces

List runs for a workspace by name

List runs for a workspace by name. Replace <WORKSPACE_NAME> with your workspace's name.

$ tfctl api /workspaces/{workspace}/runs --pathparam workspace=<WORKSPACE_NAME>

List runs for a workspace by ID

List runs for a workspace using its workspace ID. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace}/runs --pathparam workspace=<WORKSPACE_ID>

Get workspace details

Get detailed information about a specific workspace. Replace <WORKSPACE_NAME_OR_ID> with your workspace's name or ID.

$ tfctl api /workspaces/{workspace} --pathparam workspace=<WORKSPACE_NAME_OR_ID>

Get run details

Get detailed information about a specific run. Replace <RUN_ID> with your run's ID:

$ tfctl api /runs/<RUN_ID>

List all records with pagination

Fetch up to 2000 workspace records. For details on pagination options, refer to Pagination.

$ tfctl api /organizations/{organization}/workspaces --all

Filter results with query parameters

List workspaces filtered by name. Replace <SEARCH_TERM> with your search term.

$ tfctl api /organizations/{organization}/workspaces --field 'search[name]=<SEARCH_TERM>'

Create resources

To create resources, most API calls accept POST attributes with the --attribute flag, or JSON:API request bodies with the --input flag.

Create a project

Create a project using the --attribute flag to set attributes. Replace <PROJECT_NAME> with a valid name for your project.

$ tfctl api /organizations/{organization}/projects --attribute name=<PROJECT_NAME>

Create a workspace

Create a workspace with multiple attributes. Replace <WORKSPACE_NAME> with a valid workspace name that does not already exist for the given organization.

$ tfctl api /organizations/{organization}/workspaces \
  --attribute name=<WORKSPACE_NAME> \
  --attribute description="Production workspace" \
  --attribute auto-apply=true

Create a workspace variable using attributes

Create a workspace variable using the --attribute flag. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace}/vars \
  --attribute key=AWS_REGION \
  --attribute value=us-west-2 \
  --attribute category=terraform \
  --attribute description="AWS region for resources" \
  --pathparam workspace=<WORKSPACE_ID>

Create a workspace variable using a JSON:API request body

Create a workspace variable using a full JSON:API request body. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace}/vars --pathparam workspace=<WORKSPACE_ID> --input '{ "data": {
  "type":"vars",
  "attributes": {
    "key":"AWS_ACCESS_KEY_ID",
    "value":"FOOBARBAZQUX",
    "category":"env",
    "sensitive":true
  }
}}'

Update resources

Use the --method PATCH flag to send PATCH requests to update resources.

Update workspace settings

Update workspace settings using attributes. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace} --pathparam workspace=<WORKSPACE_ID> \
  --method PATCH \
  --attribute auto-apply=true \
  --attribute terraform-version=1.5.0

Update a variable

Update a variable's value. Replace <WORKSPACE_ID> with your workspace's ID and <VARIABLE_ID> with your variable's ID.

$ tfctl api /workspaces/{workspace}/vars/{variable} \
  --pathparam workspace=<WORKSPACE_ID> \
  --pathparam variable=<VARIABLE_ID> \
  --method PATCH \
  --attribute value=new-value

Delete resources

Use the --method DELETE flag to send DELETE requests to delete resources. When run in an interactive terminal, the CLI prompts the user to confirm before deleting resources. Outside an interactive terminal, such as when run by an AI agent, the CLI refuses to delete the resource unless run under tfctl harness exec --allow-delete=TYPES. Refer to the tfctl harness exec command reference for more information.

Delete a workspace

Delete a workspace. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace} --pathparam workspace=<WORKSPACE_ID> --method DELETE

Delete a variable

Delete a variable. Replace <WORKSPACE_ID> with your workspace's ID and <VARIABLE_ID> with your variable's ID.

$ tfctl api /workspaces/{workspace}/vars/{variable} \
  --pathparam workspace=<WORKSPACE_ID> \
  --pathparam variable=<VARIABLE_ID> \
  --method DELETE

Run operations

The tfctl CLI provides the tfctl run command group to start and view the status of workspace runs. You can also access the runs API directly by path.

Start a run

Start a run in a workspace. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /runs --method POST --input '{
  "data": {
    "type": "runs",
    "attributes": {
      "message": "Triggered using tfctl api"
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "<WORKSPACE_ID>"
        }
      }
    }
  }
}'

Apply a run

Apply a run that is waiting for confirmation. Replace <RUN_ID> with your run's ID.

$ tfctl api /runs/{run}/actions/apply --pathparam run=<RUN_ID> --method POST --input '{"data":{"type":"runs"}}'

Cancel a run

Cancel a running or pending run. Replace <RUN_ID> with your run's ID.

$ tfctl api /runs/{run}/actions/cancel --pathparam run=<RUN_ID> --method POST --input '{"data":{"type":"runs"}}'

Script with tfctl api

The following examples demonstrate advanced scripting patterns with tfctl api.

Extract specific fields with jq

Get just the workspace name using the --jq flag. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace} --pathparam workspace=<WORKSPACE_ID> --jq '.data.attributes.name'

List all workspace names

List all workspace names in your organization.

$ tfctl api /organizations/{organization}/workspaces --jq '.data[].attributes.name'

Capture run ID for later use

Start a run and capture its ID.

$ RUN_ID=$(tfctl api /runs --input '{...}' --jq '.data.id')
$ echo "Started run: $RUN_ID"

Chain operations

Create a workspace and then create a variable in it.

# Create workspace and capture ID
$ WORKSPACE_ID=$(tfctl api /organizations/{organization}/workspaces \
  --attribute name=my-workspace \
  --jq '.data.id')

# Create variable in the new workspace
$ tfctl api /workspaces/{workspace}/vars \
  --attribute key=ENVIRONMENT \
  --attribute value=production \
  --attribute category=terraform \
  --pathparam workspace=$WORKSPACE_ID

Use custom headers

Make a request with custom headers. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace} \
  --header 'X-Custom-Header: value' \
  --pathparam workspace=<WORKSPACE_ID>

Related

• tfctl get - Higher-level command to retrieve resources
• tfctl create - Higher-level command to create resources
• tfctl api schema - Search and inspect API operations
• Examples
• HCP Terraform API documentation