> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform Cloud

> Reference for the Tracecat Terraform Cloud integration: registered actions, required secrets, expected inputs, and example workflow usage.

## Apply run

Action ID: `tools.terraform.apply_run`

Apply a planned Terraform Cloud run to execute infrastructure changes.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="run_id" type="string" required>
  The ID of the run to apply.
</ParamField>

<ParamField path="comment" type="string | null">
  Optional comment explaining why the run is being applied.

  Default: `null`.
</ParamField>

## Create workspace variable

Action ID: `tools.terraform.create_workspace_variable`

Create a new variable in a Terraform Cloud workspace.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="key" type="string" required>
  The name of the variable.
</ParamField>

<ParamField path="value" type="string" required>
  The value of the variable.
</ParamField>

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace to create the variable in.
</ParamField>

<ParamField path="category" type="string">
  Whether this is a Terraform variable or environment variable.

  Default: `"terraform"`.

  Allowed values: `terraform`, `env`.
</ParamField>

<ParamField path="hcl" type="boolean">
  Whether the value is in HCL format.

  Default: `false`.
</ParamField>

<ParamField path="sensitive" type="boolean">
  Whether the value is sensitive and should be hidden in the UI.

  Default: `false`.
</ParamField>

## Get run details

Action ID: `tools.terraform.get_run_details`

Get details for a specific Terraform Cloud run.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="run_id" type="string" required>
  The ID of the run to get details for.
</ParamField>

## Get workspace details

Action ID: `tools.terraform.get_workspace_details`

Get details for a workspace by ID or by organization and workspace name.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="organization" type="string | null">
  The organization name. Required if workspace\_id is not provided.

  Default: `null`.
</ParamField>

<ParamField path="workspace_id" type="string | null">
  The workspace ID. If provided, organization and workspace\_name are ignored.

  Default: `null`.
</ParamField>

<ParamField path="workspace_name" type="string | null">
  The workspace name. Required if workspace\_id is not provided.

  Default: `null`.
</ParamField>

## List projects

Action ID: `tools.terraform.list_projects`

List all projects in a Terraform Cloud organization.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="organization" type="string" required>
  The name of the Terraform Cloud organization.
</ParamField>

<ParamField path="page[number]" type="integer">
  The page number to return.

  Default: `1`.
</ParamField>

<ParamField path="page[size]" type="integer">
  The number of projects to return per page.

  Default: `20`.
</ParamField>

## List runs

Action ID: `tools.terraform.list_runs`

List all runs for a Terraform Cloud workspace.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace to list runs for.
</ParamField>

<ParamField path="page[number]" type="integer">
  The page number to return.

  Default: `1`.
</ParamField>

<ParamField path="page[size]" type="integer">
  The number of runs to return per page.

  Default: `20`.
</ParamField>

## List workspace variables

Action ID: `tools.terraform.list_workspace_variables`

List all variables configured for a Terraform Cloud workspace.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace to list variables for.
</ParamField>

## List workspaces

Action ID: `tools.terraform.list_workspaces`

List all workspaces in a Terraform Cloud organization, optionally filtered by project.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="organization" type="string" required>
  The name of the Terraform Cloud organization.
</ParamField>

<ParamField path="page[number]" type="integer">
  The page number to return.

  Default: `1`.
</ParamField>

<ParamField path="page[size]" type="integer">
  The number of workspaces to return per page.

  Default: `20`.
</ParamField>

<ParamField path="project_id" type="string | null">
  Optional project ID to filter workspaces by project.

  Default: `null`.
</ParamField>

## Plan run

Action ID: `tools.terraform.plan_run`

Create a plan-only run in Terraform Cloud to preview infrastructure changes.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace to create the plan run for.
</ParamField>

<ParamField path="message" type="string | null">
  Optional message to describe the purpose of the run.

  Default: `null`.
</ParamField>

## Refresh state

Action ID: `tools.terraform.refresh_state`

Create a refresh-only run to update Terraform state with real infrastructure.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace to refresh state for.
</ParamField>

<ParamField path="message" type="string | null">
  Optional message to describe the purpose of the refresh.

  Default: `null`.
</ParamField>

## Update workspace variable

Action ID: `tools.terraform.update_workspace_variable`

Update an existing variable in a Terraform Cloud workspace.

Reference: [https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables)

### Secrets

Required secrets:

* `terraform`: required values `TERRAFORM_API_TOKEN`.

### Input fields

<ParamField path="variable_id" type="string" required>
  The ID of the variable to update.
</ParamField>

<ParamField path="workspace_id" type="string" required>
  The ID of the workspace containing the variable.
</ParamField>

<ParamField path="hcl" type="boolean | null">
  Whether the value is in HCL format.

  Default: `null`.
</ParamField>

<ParamField path="key" type="string | null">
  The name of the variable. Only required if changing the key.

  Default: `null`.
</ParamField>

<ParamField path="sensitive" type="boolean | null">
  Whether the value is sensitive.

  Default: `null`.
</ParamField>

<ParamField path="value" type="string | null">
  The value of the variable. Only required if changing the value.

  Default: `null`.
</ParamField>