# Terraform

> Run HCP Terraform from your workflows: create and configure workspaces, set their variables, upload Terraform configuration, start plans and apply, discard or cancel runs, and read the outputs your infrastructure produces.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/terraform

## Actions

### Apply run

Confirm a run that is waiting for confirmation, so its plan is applied. The apply is queued; use Get run to see it finish.

**Inputs**

- Run (`run_id`, text, required): The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment (`comment`, text): A note shown on the run in HCP Terraform.

**Outputs**

- `queued` (true/false): True once HCP Terraform accepted the request
- `run_id` (text): Id of the run

**Example output**

```json
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}
```

### Cancel run

Interrupt a run that is planning or applying, like pressing Ctrl+C. A run that is pending or waiting for confirmation is stopped with Discard run instead.

**Inputs**

- Run (`run_id`, text, required): The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment (`comment`, text): A note shown on the run in HCP Terraform.

**Outputs**

- `queued` (true/false): True once HCP Terraform accepted the request
- `run_id` (text): Id of the run

**Example output**

```json
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}
```

### Create run

Start a run in a workspace: a plan, then an apply once confirmed (or straight away with auto apply). Use Get run to follow it. A free organization runs one at a time, so others wait their turn.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Message (`message`, text): A note shown on the run in HCP Terraform.
- Configuration version (`configuration_version_id`, text): The configuration to run (cv-...), from Upload configuration. Empty uses the workspace's latest.
- Destroy (`is_destroy`, true/false): Plan to destroy every resource the workspace manages. Default: `false`.
- Refresh only (`refresh_only`, true/false): Only update the state to match real infrastructure. Can't be combined with Destroy. Default: `false`.
- Plan only (`plan_only`, true/false): Plan without ever applying. Default: `false`.
- Auto apply (`auto_apply`, text): Apply this run without confirmation (On) or wait for it (Off). Empty follows the workspace's setting. One of: `true` (On), `false` (Off).
- Target resources (`target_addrs`, list): Limit the run to these resource addresses, such as aws_instance.web, one per line or separated by commas.
- Replace resources (`replace_addrs`, list): Resource addresses to destroy and create again, one per line or separated by commas.
- Variables (`variables`, object): Values for this run only, each a Terraform variable name and a value. Text is quoted for you; write a list or map as HCL, such as ["a", "b"].

**Outputs**

- `apply` (object): The run's apply
- `auto_apply` (true/false): Whether it applies without confirmation
- `configuration_version_id` (text): Id of the configuration it runs (cv-...)
- `created_at` (text): When it was created (ISO 8601)
- `has_changes` (true/false): Whether its plan has changes
- `id` (text): Run id (run-...)
- `is_cancelable` (true/false): True when Cancel run will work
- `is_confirmable` (true/false): True when it is waiting for confirmation, so Apply run will work
- `is_destroy` (true/false): Whether it destroys every resource
- `is_discardable` (true/false): True when Discard run will work
- `is_final` (true/false): True once the run has stopped and won't move on by itself, such as applied, discarded, errored or canceled
- `message` (text): The run's message
- `plan` (object): The run's plan
- `plan_only` (true/false): Whether it only plans
- `refresh_only` (true/false): Whether it only refreshes state
- `replace_addrs` (list): Resources it replaces
- `source` (text): Where it was started, such as tfe-api or tfe-ui
- `status` (text): Run status, such as planning, planned, applied or errored
- `status_timestamps` (object): When the run reached each status, keyed like planned_at or applied_at
- `target_addrs` (list): Resources it is limited to
- `trigger_reason` (text): Why it was started
- `workspace_id` (text): Id of its workspace (ws-...)

**Example output**

```json
{
  "apply": {
    "id": "apply-ywLgq6wmfgPBE4QQ",
    "resource_additions": null,
    "resource_changes": null,
    "resource_destructions": null,
    "resource_imports": null,
    "status": null
  },
  "auto_apply": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "created_at": "2026-10-20T08:00:00.000Z",
  "has_changes": false,
  "id": "run-CZcmD7eagjhyX0vN",
  "is_cancelable": false,
  "is_confirmable": false,
  "is_destroy": false,
  "is_discardable": true,
  "is_final": false,
  "message": "Queued from Lodol",
  "plan": {
    "id": "plan-6JmHBoKKeBDvnQyW",
    "resource_additions": null,
    "resource_changes": null,
    "resource_destructions": null,
    "resource_imports": null,
    "status": null
  },
  "plan_only": false,
  "refresh_only": false,
  "replace_addrs": null,
  "source": "tfe-api",
  "status": "pending",
  "status_timestamps": {
    "plan_queueable_at": "2026-10-20T08:00:01+00:00"
  },
  "target_addrs": null,
  "trigger_reason": "manual",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Create variable

Add a Terraform variable or an environment variable to a workspace. Every later run uses it.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Key (`key`, text, required): The variable's name, such as region or AWS_REGION. One per category in a workspace.
- Category (`category`, text, required): A Terraform variable fills a variable block in the configuration; an environment variable is set in the run's shell. One of: `terraform` (Terraform variable), `env` (Environment variable).
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Value (`value`, text): The value. Empty sets an empty value.
- Description (`description`, text): A description shown in HCP Terraform.
- HCL (`hcl`, true/false): Read the value as HCL code, such as a list or map. Has no effect on environment variables. Default: `false`.
- Sensitive (`sensitive`, true/false): Hide the value: it is written once and can't be read back. Default: `false`.

**Outputs**

- `category` (text): terraform or env
- `description` (text): Description
- `hcl` (true/false): Whether the value is read as HCL
- `id` (text): Variable id (var-...)
- `key` (text): Variable name
- `sensitive` (true/false): Whether the value is hidden
- `value` (text): Its value; empty for a sensitive variable
- `version_id` (text): Id of this version of the variable
- `workspace_id` (text): Id of its workspace (ws-...)

**Example output**

```json
{
  "category": "terraform",
  "description": "Where to deploy",
  "hcl": false,
  "id": "var-EavQ1LztoRTQHSNT",
  "key": "region",
  "sensitive": false,
  "value": "us-east-1",
  "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Create workspace

Create a workspace that is run from Lodol: upload its configuration with Upload configuration, then start runs with Create run.

**Inputs**

- Organization (`organization`, text, required): The HCP Terraform organization. Pick one, or type its name.
- Name (`name`, text, required): The workspace name: letters, numbers, - and _, unique in the organization.
- Description (`description`, text): A description of the workspace.
- Project (`project_id`, text): The project to put it in. Empty means the organization's default project.
- Execution mode (`execution_mode`, text): Where Terraform runs. Leave empty for the organization's default. One of: `remote` (Remote (HCP Terraform runs Terraform)), `local` (Local (HCP Terraform only stores state)).
- Auto apply (`auto_apply`, true/false): Apply a successful plan without waiting for confirmation. Default: `false`.
- Terraform version (`terraform_version`, text): An exact version such as 1.9.8, or a constraint such as ~> 1.9.0. A new workspace gets the latest version when this is empty.
- Working directory (`working_directory`, text): The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
- Tags (`tags`, object): Up to 10 tags, each a key and a value, such as env = prod.

**Outputs**

- `auto_apply` (true/false): Whether a successful plan is applied without confirmation
- `created_at` (text): When it was created (ISO 8601)
- `current_run_id` (text): Id of its current run (run-...)
- `description` (text): Description
- `execution_mode` (text): Where Terraform runs: remote, local or agent
- `id` (text): Workspace id (ws-...)
- `latest_change_at` (text): When its state or configuration last changed (ISO 8601)
- `locked` (true/false): Whether the workspace is locked
- `locked_reason` (text): Why it was locked
- `name` (text): Workspace name
- `organization` (text): Organization name
- `project_id` (text): Id of the project it is in (prj-...)
- `resource_count` (number): How many resources its state manages
- `terraform_version` (text): Terraform version it runs
- `updated_at` (text): When it was last changed (ISO 8601)
- `url` (text): Link to the workspace in HCP Terraform
- `working_directory` (text): Directory Terraform runs in, relative to the configuration root

**Example output**

```json
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}
```

### Delete variable

Remove a variable from a workspace.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Variable (`variable_id`, text, required): The variable. Pick one of the workspace's, or give its id (var-...).
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

**Outputs**

- `deleted` (true/false): True once the variable is deleted
- `variable_id` (text): Id of the deleted variable
- `workspace_id` (text): Id of its workspace (ws-...)

**Example output**

```json
{
  "deleted": true,
  "variable_id": "var-EavQ1LztoRTQHSNT",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Delete workspace

Delete a workspace. By default it is only deleted when it manages no resources; Force delete removes it anyway, leaving its infrastructure in place but no longer tracked.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Force delete (`force`, true/false): Delete it even if it still manages resources. Those resources are not destroyed. Only organization owners can force delete. Default: `false`.

**Outputs**

- `deleted` (true/false): True once the workspace is deleted
- `forced` (true/false): Whether it was force deleted
- `workspace_id` (text): Id of the deleted workspace

**Example output**

```json
{
  "deleted": true,
  "forced": false,
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Discard run

Discard a run that is pending or waiting for confirmation, so it is never applied. A run that is planning or applying is stopped with Cancel run instead.

**Inputs**

- Run (`run_id`, text, required): The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment (`comment`, text): A note shown on the run in HCP Terraform.

**Outputs**

- `queued` (true/false): True once HCP Terraform accepted the request
- `run_id` (text): Id of the run

**Example output**

```json
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}
```

### Get outputs

Get the outputs of a workspace's latest state, such as an IP address or a URL the configuration produced. Sensitive outputs come back null.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

**Outputs**

- `count` (number): How many outputs there are
- `items` (list): Each output with its type
- `outputs` (object): Each output's value by its name, so @step.outputs.vpc_id reads the vpc_id output
- `workspace_id` (text): Id of the workspace (ws-...)

**Example output**

```json
{
  "count": 2,
  "items": [
    {
      "id": "wsout-xFAmCR3VkBGepcee",
      "name": "vpc_id",
      "sensitive": false,
      "type": "string",
      "value": "vpc-0a1b2c3d4e5f67890"
    },
    {
      "id": "wsout-tY7ZpQ9wNcA6kLmB",
      "name": "db_password",
      "sensitive": true,
      "type": "string",
      "value": null
    }
  ],
  "outputs": {
    "db_password": null,
    "vpc_id": "vpc-0a1b2c3d4e5f67890"
  },
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Get run

Get a run's status and what its plan and apply add, change and destroy. Repeat it to wait for a run to finish.

**Inputs**

- Run (`run_id`, text, required): The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.

**Outputs**

- `apply` (object): The run's apply
- `auto_apply` (true/false): Whether it applies without confirmation
- `configuration_version_id` (text): Id of the configuration it runs (cv-...)
- `created_at` (text): When it was created (ISO 8601)
- `has_changes` (true/false): Whether its plan has changes
- `id` (text): Run id (run-...)
- `is_cancelable` (true/false): True when Cancel run will work
- `is_confirmable` (true/false): True when it is waiting for confirmation, so Apply run will work
- `is_destroy` (true/false): Whether it destroys every resource
- `is_discardable` (true/false): True when Discard run will work
- `is_final` (true/false): True once the run has stopped and won't move on by itself, such as applied, discarded, errored or canceled
- `message` (text): The run's message
- `plan` (object): The run's plan
- `plan_only` (true/false): Whether it only plans
- `refresh_only` (true/false): Whether it only refreshes state
- `replace_addrs` (list): Resources it replaces
- `source` (text): Where it was started, such as tfe-api or tfe-ui
- `status` (text): Run status, such as planning, planned, applied or errored
- `status_timestamps` (object): When the run reached each status, keyed like planned_at or applied_at
- `target_addrs` (list): Resources it is limited to
- `trigger_reason` (text): Why it was started
- `workspace_id` (text): Id of its workspace (ws-...)

**Example output**

```json
{
  "apply": {
    "id": "apply-ywLgq6wmfgPBE4QQ",
    "resource_additions": 0,
    "resource_changes": 0,
    "resource_destructions": 0,
    "resource_imports": 0,
    "status": "unreachable"
  },
  "auto_apply": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "created_at": "2026-10-20T08:00:00.000Z",
  "has_changes": true,
  "id": "run-CZcmD7eagjhyX0vN",
  "is_cancelable": false,
  "is_confirmable": true,
  "is_destroy": false,
  "is_discardable": true,
  "is_final": false,
  "message": "Queued from Lodol",
  "plan": {
    "id": "plan-6JmHBoKKeBDvnQyW",
    "resource_additions": 1,
    "resource_changes": 0,
    "resource_destructions": 0,
    "resource_imports": 0,
    "status": "finished"
  },
  "plan_only": false,
  "refresh_only": false,
  "replace_addrs": null,
  "source": "tfe-api",
  "status": "planned",
  "status_timestamps": {
    "plan_queueable_at": "2026-10-20T08:00:01+00:00",
    "planned_at": "2026-10-20T08:00:30+00:00"
  },
  "target_addrs": null,
  "trigger_reason": "manual",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Get workspace

Get a workspace's settings, lock state, resource count and current run, by its id, its name or its link.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

**Outputs**

- `auto_apply` (true/false): Whether a successful plan is applied without confirmation
- `created_at` (text): When it was created (ISO 8601)
- `current_run_id` (text): Id of its current run (run-...)
- `description` (text): Description
- `execution_mode` (text): Where Terraform runs: remote, local or agent
- `id` (text): Workspace id (ws-...)
- `latest_change_at` (text): When its state or configuration last changed (ISO 8601)
- `locked` (true/false): Whether the workspace is locked
- `locked_reason` (text): Why it was locked
- `name` (text): Workspace name
- `organization` (text): Organization name
- `project_id` (text): Id of the project it is in (prj-...)
- `resource_count` (number): How many resources its state manages
- `terraform_version` (text): Terraform version it runs
- `updated_at` (text): When it was last changed (ISO 8601)
- `url` (text): Link to the workspace in HCP Terraform
- `working_directory` (text): Directory Terraform runs in, relative to the configuration root

**Example output**

```json
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}
```

### List organizations

List the HCP Terraform organizations the token's user belongs to, with each one's plan.

**Inputs**

- Search (`search`, text): Only organizations whose name or email contains this.
- Page (`page`, number): Which page of results to return, starting at 1. At least 1.
- Page size (`page_size`, number): How many to return per page, up to 100. The default is 20. From 1 to 100.

**Outputs**

- `count` (number): How many records are on this page
- `has_more` (true/false): True when there are more pages
- `next_page` (number): The next page number, when there is one
- `organizations` (list): The organizations
- `page` (number): The page number
- `total_count` (number): How many records match in all

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "organizations": [
    {
      "can_create_workspace": true,
      "created_at": "2026-01-12T09:00:00.000Z",
      "default_execution_mode": "remote",
      "email": "platform@example.com",
      "name": "my-company",
      "plan_identifier": "free"
    }
  ],
  "page": 1,
  "total_count": 1
}
```

### List runs

List a workspace's runs, newest first. Plan only runs are left out unless chosen under Operations. HCP Terraform allows this 30 times a minute, so follow one run with Get run instead.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Statuses (`statuses`, list): Only runs with one of these statuses. One or more of: `pending`, `fetching`, `fetching_completed` (Fetching completed), `pre_plan_running` (Pre plan running), `pre_plan_completed` (Pre plan completed), `queuing`, `plan_queued` (Plan queued), `planning`, `planned`, `cost_estimating` (Cost estimating), and 17 more.
- Operations (`operations`, list): Only runs of these kinds. One or more of: `plan_only` (Plan only), `plan_and_apply` (Plan and apply), `save_plan` (Saved plan), `refresh_only` (Refresh only), `destroy`, `empty_apply` (Empty apply), `action_only` (Action only).
- Status group (`status_group`, text): Only runs in progress, finished, or able to be discarded. One of: `non_final` (Still in progress), `final` (Finished), `discardable` (Can be discarded).
- Source (`source`, text): Only runs started this way. One of: `tfe-ui` (HCP Terraform website), `tfe-api` (API (including Lodol)), `tfe-configuration-version` (Configuration upload).
- Page (`page`, number): Which page of results to return, starting at 1. At least 1.
- Page size (`page_size`, number): How many to return per page, up to 100. The default is 20. From 1 to 100.

**Outputs**

- `count` (number): How many records are on this page
- `has_more` (true/false): True when there are more pages
- `next_page` (number): The next page number, when there is one
- `page` (number): The page number
- `runs` (list): The runs, newest first
- `total_count` (number): How many records match in all

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "page": 1,
  "runs": [
    {
      "apply": {
        "id": "apply-ywLgq6wmfgPBE4QQ",
        "resource_additions": null,
        "resource_changes": null,
        "resource_destructions": null,
        "resource_imports": null,
        "status": null
      },
      "auto_apply": false,
      "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
      "created_at": "2026-10-20T08:00:00.000Z",
      "has_changes": true,
      "id": "run-CZcmD7eagjhyX0vN",
      "is_cancelable": false,
      "is_confirmable": true,
      "is_destroy": false,
      "is_discardable": true,
      "is_final": false,
      "message": "Queued from Lodol",
      "plan": {
        "id": "plan-6JmHBoKKeBDvnQyW",
        "resource_additions": null,
        "resource_changes": null,
        "resource_destructions": null,
        "resource_imports": null,
        "status": null
      },
      "plan_only": false,
      "refresh_only": false,
      "replace_addrs": null,
      "source": "tfe-api",
      "status": "planned",
      "status_timestamps": {
        "plan_queueable_at": "2026-10-20T08:00:01+00:00",
        "planned_at": "2026-10-20T08:00:30+00:00"
      },
      "target_addrs": null,
      "trigger_reason": "manual",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    }
  ],
  "total_count": 1
}
```

### List variables

List a workspace's Terraform and environment variables. Sensitive values come back empty.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Category (`category`, text): Only Terraform variables, or only environment variables. One of: `terraform` (Terraform variable), `env` (Environment variable).

**Outputs**

- `count` (number): How many variables there are
- `variables` (list): The variables
- `workspace_id` (text): Id of the workspace (ws-...)

**Example output**

```json
{
  "count": 2,
  "variables": [
    {
      "category": "terraform",
      "description": "Where to deploy",
      "hcl": false,
      "id": "var-EavQ1LztoRTQHSNT",
      "key": "region",
      "sensitive": false,
      "value": "us-east-1",
      "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    },
    {
      "category": "env",
      "description": null,
      "hcl": false,
      "id": "var-ffbP3LrZ9yPvdUXD",
      "key": "AWS_SECRET_ACCESS_KEY",
      "sensitive": true,
      "value": null,
      "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    }
  ],
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### List workspaces

List an organization's workspaces, optionally searched by name or filtered by project, tag or the status of their current run.

**Inputs**

- Organization (`organization`, text, required): The HCP Terraform organization. Pick one, or type its name.
- Search (`search`, text): Part of a workspace name. Use * as a wildcard, as in prod-* or *-network.
- Project (`project_id`, text): Only workspaces in this project.
- Current run status (`current_run_status`, text): Only workspaces whose current run has this status. One of: `pending`, `fetching`, `fetching_completed` (Fetching completed), `pre_plan_running` (Pre plan running), `pre_plan_completed` (Pre plan completed), `queuing`, `plan_queued` (Plan queued), `planning`, `planned`, `cost_estimating` (Cost estimating), and 17 more.
- Tag key (`tag_key`, text): Only workspaces with a tag of this key.
- Tag value (`tag_value`, text): With Tag key: only that tag with this value.
- Sort by (`sort`, text): The order to list them in. The default is by name. One of: `name` (Name, A to Z), `-name` (Name, Z to A), `-latest-change-at` (Most recently changed first), `latest-change-at` (Least recently changed first), `-current-run.created-at` (Newest current run first), `current-run.created-at` (Oldest current run first).
- Page (`page`, number): Which page of results to return, starting at 1. At least 1.
- Page size (`page_size`, number): How many to return per page, up to 100. The default is 20. From 1 to 100.

**Outputs**

- `count` (number): How many records are on this page
- `has_more` (true/false): True when there are more pages
- `next_page` (number): The next page number, when there is one
- `page` (number): The page number
- `total_count` (number): How many records match in all
- `workspaces` (list): The workspaces

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "page": 1,
  "total_count": 1,
  "workspaces": [
    {
      "auto_apply": false,
      "created_at": "2026-09-01T10:15:00.000Z",
      "current_run_id": "run-CZcmD7eagjhyX0vN",
      "description": "VPC and subnets for production",
      "execution_mode": "remote",
      "id": "ws-SihZTyXKfNXUWuUa",
      "latest_change_at": "2026-10-20T08:00:00.000Z",
      "locked": false,
      "locked_reason": "",
      "name": "networking-prod",
      "organization": "my-company",
      "project_id": "prj-jT92VLSFpv8FwKtc",
      "resource_count": 12,
      "terraform_version": "1.9.8",
      "updated_at": "2026-10-20T08:00:00.000Z",
      "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
      "working_directory": ""
    }
  ]
}
```

### Lock workspace

Lock a workspace so no new run can start in it until it is unlocked.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Reason (`reason`, text): Why it is locked, shown in HCP Terraform.

**Outputs**

- `auto_apply` (true/false): Whether a successful plan is applied without confirmation
- `created_at` (text): When it was created (ISO 8601)
- `current_run_id` (text): Id of its current run (run-...)
- `description` (text): Description
- `execution_mode` (text): Where Terraform runs: remote, local or agent
- `id` (text): Workspace id (ws-...)
- `latest_change_at` (text): When its state or configuration last changed (ISO 8601)
- `locked` (true/false): Whether the workspace is locked
- `locked_reason` (text): Why it was locked
- `name` (text): Workspace name
- `organization` (text): Organization name
- `project_id` (text): Id of the project it is in (prj-...)
- `resource_count` (number): How many resources its state manages
- `terraform_version` (text): Terraform version it runs
- `updated_at` (text): When it was last changed (ISO 8601)
- `url` (text): Link to the workspace in HCP Terraform
- `working_directory` (text): Directory Terraform runs in, relative to the configuration root

**Example output**

```json
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": true,
  "locked_reason": "Maintenance window",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}
```

### Unlock workspace

Unlock a workspace. Force unlock releases a lock held by another user or a run.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Force unlock (`force`, true/false): Release a lock someone else or a run holds. Needs admin access to the workspace. Default: `false`.

**Outputs**

- `auto_apply` (true/false): Whether a successful plan is applied without confirmation
- `created_at` (text): When it was created (ISO 8601)
- `current_run_id` (text): Id of its current run (run-...)
- `description` (text): Description
- `execution_mode` (text): Where Terraform runs: remote, local or agent
- `id` (text): Workspace id (ws-...)
- `latest_change_at` (text): When its state or configuration last changed (ISO 8601)
- `locked` (true/false): Whether the workspace is locked
- `locked_reason` (text): Why it was locked
- `name` (text): Workspace name
- `organization` (text): Organization name
- `project_id` (text): Id of the project it is in (prj-...)
- `resource_count` (number): How many resources its state manages
- `terraform_version` (text): Terraform version it runs
- `updated_at` (text): When it was last changed (ISO 8601)
- `url` (text): Link to the workspace in HCP Terraform
- `working_directory` (text): Directory Terraform runs in, relative to the configuration root

**Example output**

```json
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}
```

### Update variable

Change a workspace variable's key, value, description or category. Only the fields filled in change.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Variable (`variable_id`, text, required): The variable. Pick one of the workspace's, or give its id (var-...).
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- New key (`key`, text): A new name for the variable.
- Value (`value`, text): A new value. Empty keeps the current one.
- Description (`description`, text): A new description.
- Category (`category`, text): Move it to the other category. One of: `terraform` (Terraform variable), `env` (Environment variable).
- HCL (`hcl`, text): Read the value as HCL code (On) or as text (Off). Empty keeps the current setting. One of: `true` (On), `false` (Off).
- Make sensitive (`sensitive`, true/false): Hide the value from now on. A sensitive variable stays sensitive, so leaving this off keeps its current setting. Default: `false`.

**Outputs**

- `category` (text): terraform or env
- `description` (text): Description
- `hcl` (true/false): Whether the value is read as HCL
- `id` (text): Variable id (var-...)
- `key` (text): Variable name
- `sensitive` (true/false): Whether the value is hidden
- `value` (text): Its value; empty for a sensitive variable
- `version_id` (text): Id of this version of the variable
- `workspace_id` (text): Id of its workspace (ws-...)

**Example output**

```json
{
  "category": "terraform",
  "description": "Where to deploy",
  "hcl": false,
  "id": "var-EavQ1LztoRTQHSNT",
  "key": "region",
  "sensitive": false,
  "value": "us-east-1",
  "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```

### Update workspace

Change a workspace's settings. Only the fields filled in change. Renaming a workspace changes its link.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- New name (`name`, text): A new name: letters, numbers, - and _.
- Description (`description`, text): A description of the workspace.
- Execution mode (`execution_mode`, text): Where Terraform runs. Leave empty for the organization's default. One of: `remote` (Remote (HCP Terraform runs Terraform)), `local` (Local (HCP Terraform only stores state)).
- Auto apply (`auto_apply`, text): Turn applying without confirmation on or off. Empty keeps the current setting. One of: `true` (On), `false` (Off).
- Terraform version (`terraform_version`, text): An exact version such as 1.9.8, or a constraint such as ~> 1.9.0. A new workspace gets the latest version when this is empty.
- Working directory (`working_directory`, text): The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
- Move to project (`project_id`, text): Move the workspace to this project. Needs admin access to both projects.

**Outputs**

- `auto_apply` (true/false): Whether a successful plan is applied without confirmation
- `created_at` (text): When it was created (ISO 8601)
- `current_run_id` (text): Id of its current run (run-...)
- `description` (text): Description
- `execution_mode` (text): Where Terraform runs: remote, local or agent
- `id` (text): Workspace id (ws-...)
- `latest_change_at` (text): When its state or configuration last changed (ISO 8601)
- `locked` (true/false): Whether the workspace is locked
- `locked_reason` (text): Why it was locked
- `name` (text): Workspace name
- `organization` (text): Organization name
- `project_id` (text): Id of the project it is in (prj-...)
- `resource_count` (number): How many resources its state manages
- `terraform_version` (text): Terraform version it runs
- `updated_at` (text): When it was last changed (ISO 8601)
- `url` (text): Link to the workspace in HCP Terraform
- `working_directory` (text): Directory Terraform runs in, relative to the configuration root

**Example output**

```json
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}
```

### Upload configuration

Upload Terraform files to a workspace and wait until HCP Terraform has read them, so the next Create run uses them.

**Inputs**

- Workspace (`workspace`, text, required): The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Configuration (`configuration`, text, required): The Terraform code, uploaded as main.tf.
- Organization (`organization`, text): The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
- Additional files (`additional_files`, object): More files, each a file name and its content, such as variables.tf. Use a path like modules/net/main.tf for a file in a folder.
- Queue a run (`auto_queue_runs`, true/false): Start a run as soon as the upload is ready. Leave off to start one with a Create run step. Default: `false`.
- Speculative (`speculative`, true/false): Use the upload only for plans that can't be applied, and don't make it the workspace's current configuration. Default: `false`.

**Outputs**

- `auto_queue_runs` (true/false): Whether a run was queued with it
- `configuration_version_id` (text): Id of the new configuration version (cv-...)
- `files` (list): The files that were uploaded
- `speculative` (true/false): Whether it is for plans only
- `status` (text): Its status, uploaded once it is ready
- `workspace_id` (text): Id of the workspace (ws-...)

**Example output**

```json
{
  "auto_queue_runs": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "files": [
    "main.tf",
    "variables.tf"
  ],
  "speculative": false,
  "status": "uploaded",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}
```
