<!-- Generated by scripts/generate-llms.mjs from docs/connectors/terraform.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/terraform

# Connect Terraform

Tasks call HCP Terraform through `qbash.integrations.terraform` with an API token you store on the Connectors page. The connector reads organizations, workspaces, variables, variable sets, runs with their plans and applies, configuration versions, state versions and their outputs, projects and notification configurations. Its writes create and update workspaces and workspace variables, create variable sets and their variables, queue runs, create configuration versions and create projects.

It covers HCP Terraform (formerly Terraform Cloud) only. Self-hosted Terraform Enterprise and the open-source Terraform CLI are different products and are not supported. No method deletes anything, applies or discards a run, changes state, or manages teams and tokens.

After you connect Terraform, you can add its tools to a [qbash MCP server](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) for ChatGPT, Claude and other MCP clients, or call it from a Python task.

## Get an HCP Terraform account

1. Create an account at [app.terraform.io](https://app.terraform.io/public/signup/account). The sign-up form asks for a username, email address and password. HashiCorp's docs do not say whether the Free plan needs a credit card.
2. Create an organization and choose the **Free** plan. It costs nothing for up to 500 managed resources, with one concurrent remote run. It includes unlimited workspaces and projects and API access, but not teams. Teams are a paid-plan feature, and so are policies and policy sets, which this connector does not cover.
3. Open **Account settings**, then **Tokens**, and click **Create an API token**.
4. Choose a short expiration, such as 30 days.
5. Copy the token. HCP Terraform shows it once, so paste it straight into qbash or keep it somewhere safe.
6. Confirm the token can write. In the organization, create a test workspace in the HCP Terraform UI, or run `create_project` from a task and check the project appears.

Essentials is pay-as-you-go per managed resource per hour, and HashiCorp's docs point to the pricing page on its [Terraform site](https://www.hashicorp.com/products/terraform) for current rates. Standard and Premium need a conversation with HashiCorp sales. HCP Europe organizations use contract billing through sales.

## Pick a token type

HCP Terraform has no scopes, so the token's owner decides what qbash can do.

| Token | Permissions | Notes |
| --- | --- | --- |
| User | The permissions of the user who made it | The practical choice on the Free plan, which has no teams |
| Team | The access of the team on its workspaces | Needs a paid plan. A team token can start runs and create configuration versions |
| Organization | Can create and configure workspaces and teams | Cannot start runs or create configuration versions |

Avoid a token from an organization owner. Create it from a user or team that has only the workspaces your tasks need. An organization can disable user tokens, and HCP Terraform then refuses them on that organization's resources.

The API allows 30 requests per second per user, counted across all of that user's tokens. Some endpoints allow fewer. List runs allows 30 requests per minute. A 429 reaches your task as a rate limit error, and the task should wait a few seconds before calling again.

## Add the token in qbash

1. Open **Connectors**, then **Terraform**, and click **Connect**.
2. Fill in **Credential Name**, such as "qbash platform workspaces", and paste the token into **API Token**.
3. Save. qbash checks the token with HCP Terraform and saves it only if HCP Terraform accepts it.
4. In the task editor, choose **Add connector** from the Package **+** menu and select the credential. See [Task resources](https://qbash.com/docs-markdown/tasks/task-editor.md#resources).

## Check recent runs from a task

```python
workspaces = qbash.integrations.terraform.list_workspaces(organization="my-organization")
for workspace in workspaces["workspaces"]:
    runs = qbash.integrations.terraform.list_runs(
        workspace_id=workspace["id"],
        status=["errored"],
        page_size=5,
    )
    qbash.output({"workspace": workspace["name"], "errored_runs": runs["runs"]})
```

Each response is JSON:API flattened to plain keys. An item has `id`, `type` and its attributes with `-` changed to `_`, and a `relationships` map of related IDs. A run's `relationships.plan` and `relationships.apply` go to `get_plan` and `get_apply`. List methods return `next_cursor`. Pass it back as `cursor` until it is `None`. The [SDK Reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md) lists every method and its parameters.

## Methods

| Method | Resource | Access |
| --- | --- | --- |
| `list_organizations` | Organizations | Read |
| `get_organization` | Organizations | Read |
| `list_workspaces` | Workspaces | Read |
| `get_workspace` | Workspaces | Read |
| `create_workspace` | Workspaces | Write |
| `update_workspace` | Workspaces | Write |
| `list_workspace_variables` | Workspace variables | Read |
| `create_workspace_variable` | Workspace variables | Write |
| `update_workspace_variable` | Workspace variables | Write |
| `list_variable_sets` | Variable sets | Read |
| `create_variable_set` | Variable sets | Write |
| `create_variable_set_variable` | Variable sets | Write |
| `list_runs` | Runs | Read |
| `get_run` | Runs | Read |
| `create_run` | Runs | Write |
| `get_plan` | Plans | Read |
| `get_apply` | Applies | Read |
| `list_configuration_versions` | Configuration versions | Read |
| `create_configuration_version` | Configuration versions | Write |
| `list_state_versions` | State versions | Read |
| `get_current_state_version` | State versions | Read |
| `list_state_version_outputs` | State version outputs | Read |
| `list_projects` | Projects | Read |
| `create_project` | Projects | Write |
| `list_notification_configurations` | Notification configurations | Read |

## Details that affect results

- `create_run` queues a plan and always sends auto-apply as false, so the run waits for a person to confirm it in HCP Terraform even on a workspace with auto-apply on. `plan_only=True` queues a plan that can never apply. Destroy runs cannot be requested, and `update_workspace` cannot turn auto-apply on.
- `create_run` and `create_configuration_version` need a user or team token. An organization token gets a 403.
- `create_configuration_version` returns an `upload_url` only in that response. This connector does not upload the configuration archive. The version is always created with `auto_queue_runs` set to `False`, so uploading it never starts a run. Use `create_run` to plan it.
- The value of a sensitive variable or sensitive output is `None` in every read. A sensitive variable is write-only once saved.
- `list_notification_configurations` shows only the host of each webhook URL and leaves out the token.
- `list_state_versions` needs both `organization` and `workspace_name`. The state version upload URLs are left out of the results.
- A 404 can mean the token's user or team lacks permission to see the resource, because HCP Terraform hides what a token cannot read.
- A 401 marks the credential as needing a new token. A 403 does not, and its message points to the token type, its expiration date and its permissions.
- Saving a token checks it against the organizations list. A 403 or 404 there still lets the token save, because an organization token cannot list organizations. Only a 401 rejects it.
- `list_workspace_variables` returns every variable in one response and has no paging.
