> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to HCP Terraform

The HCP Terraform connector lets your AI agent act in each user's HCP Terraform account. Each user connects their own HCP Terraform access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 30 tools.

**Authentication:** Bearer Token
**Categories:** Developer Tools, Automation
**Tools:** 30: 17 read, 11 write, 2 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=TERRAFORM)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the HCP Terraform connection

   In **AgentKit > Connections**, create a HCP Terraform connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'terraform'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize HCP Terraform:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'terraform_organizations_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "terraform"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize HCP Terraform:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="terraform_organizations_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their HCP Terraform credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'terraform_organization_get',
  toolInput: {
    organization_name: '<organization_name>',
  },
  connector: 'terraform',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="terraform_organization_get",
    tool_input={
        "organization_name": "<organization_name>",
    },
    connection_name="terraform",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `terraform_organization_get`

Get Organization · Read-only

Get one HCP Terraform organization by name.
Returns its settings: email, default execution mode, collaborator auth policy, cost estimation, session settings and the token's permissions on it.
Use terraform_organization_get for a known name. Use terraform_organizations_list to find names.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_organization_runs_list`

List Organization Runs · Read-only

List runs across all workspaces in an HCP Terraform organization, with workspace, status and text filters.
Returns run records with id, status, message and created-at; by default only runs from the last year.
Use terraform_organization_runs_list to find active or failed runs anywhere. Use terraform_runs_list for one workspace.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `filter_operation` (`string`, optional): Comma-separated run operations: plan_only, plan_and_apply, save_plan, refresh_only, destroy, empty_apply, action_only. plan_only runs are left out unless listed. Example: plan_and_apply,destroy
- `filter_source` (`string`, optional): Comma-separated run sources: tfe-ui, tfe-api, tfe-configuration-version. Example: tfe-api
- `filter_status` (`string`, optional): Comma-separated run statuses to return, such as planned,errored,applied,policy_checked,discarded. Example: planned,errored
- `filter_status_group` (`string`, optional): One status group: non_final (running or waiting), final (finished) or discardable. Example: non_final. One of: `non_final`, `final`, `discardable`.
- `filter_timeframe` (`string`, optional): A year such as 2025, or year for the past year. Example: 2025
- `filter_workspace_names` (`string`, optional): Comma-separated workspace names to include. Example: networking-prod,app-prod
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `search_basic` (`string`, optional): Matches VCS username, commit SHA, run ID or run message; ignored if search_user or search_commit is set. Example: fix subnet
- `search_commit` (`string`, optional): Commit SHA the run used. Example: 7d0e1b5
- `search_user` (`string`, optional): VCS username that triggered the run. Example: octocat

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_organizations_list`

List Organizations · Read-only

List the HCP Terraform organizations the token can access, optionally searching by name or notification email.
Returns organization records with id (the organization name), email, plan and permissions, plus pagination meta.
Use terraform_organizations_list to find organization names. Use terraform_organization_get for one organization's settings.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `q` (`string`, optional): Search string that matches organization names and notification emails. Takes precedence over q_email and q_name. Example: acme
- `q_email` (`string`, optional): Search string matched against the organization notification email only. Example: ops@acme.com
- `q_name` (`string`, optional): Search string matched against the organization name only. Example: acme-prod

Example input: `{}`

### `terraform_plan_get`

Get Plan · Read-only

Get one HCP Terraform plan by ID.
Returns its status, resource additions, changes, destructions and imports, and log-read-url, a short-lived URL to download the plan log.
Use terraform_plan_get with the plan ID from terraform_run_get relationships.plan.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `plan_id` (`string`, required): ID of the plan, starting with plan-. Find it in a run's relationships.plan.data.id. Example: plan-8F5JFydVYAmtTjET

Example input: `{"plan_id":"<plan_id>"}`

### `terraform_project_get`

Get Project · Read-only

Get one HCP Terraform project by ID.
Returns the project name, description, default execution mode, auto-destroy setting and its organization.
Use terraform_project_get for a known ID. Use terraform_projects_list to search by name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `project_id` (`string`, required): ID of the project, starting with prj-. Example: prj-WsVcWRr7SSxRDEDx

Example input: `{"project_id":"<project_id>"}`

### `terraform_projects_list`

List Projects · Read-only

List the projects in an HCP Terraform organization, optionally searching by name.
Returns project records with id (prj-...), name, description, default execution mode and workspace count.
Use terraform_projects_list to find project IDs. Use terraform_project_get for one project.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `filter_names` (`string`, optional): Exact project name, or several comma-separated names, to return (case-insensitive). Example: Default Project,networking
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `q` (`string`, optional): Case-insensitive search on project name. Ignored when filter_names is set. Example: networking
- `sort` (`string`, optional): Sort order: name, or -name for reverse alphabetical. Example: -name. One of: `name`, `-name`.

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_run_get`

Get Run · Read-only

Get one HCP Terraform run by ID.
Returns its status, status timestamps, message, flags (is-destroy, refresh-only, plan-only), actions it allows and relationships to its plan, apply and workspace.
Use terraform_run_get to check progress after terraform_run_create. Use terraform_plan_get for the plan's resource counts and log URL.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `run_id` (`string`, required): ID of the run to get, starting with run-. Use terraform_runs_list to find it. Example: run-CZcmD7eagjhyX0vN

Example input: `{"run_id":"<run_id>"}`

### `terraform_runs_list`

List Workspace Runs · Read-only

List runs in one HCP Terraform workspace, newest first, with status, operation and text filters.
Returns run records with id (run-...), status, message, is-destroy, created-at and status timestamps. Rate limited to 30 requests per minute.
Use terraform_runs_list for one workspace. Use terraform_organization_runs_list across workspaces. Use terraform_run_get for one run.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa
- `filter_operation` (`string`, optional): Comma-separated run operations: plan_only, plan_and_apply, save_plan, refresh_only, destroy, empty_apply, action_only. plan_only runs are left out unless listed. Example: plan_and_apply,destroy
- `filter_source` (`string`, optional): Comma-separated run sources: tfe-ui, tfe-api, tfe-configuration-version. Example: tfe-api
- `filter_status` (`string`, optional): Comma-separated run statuses to return, such as planned,errored,applied,policy_checked,discarded. Example: planned,errored
- `filter_status_group` (`string`, optional): One status group: non_final (running or waiting), final (finished) or discardable. Example: non_final. One of: `non_final`, `final`, `discardable`.
- `filter_timeframe` (`string`, optional): A year such as 2025, or year for the past year. Example: 2025
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `search_basic` (`string`, optional): Matches VCS username, commit SHA, run ID or run message; ignored if search_user or search_commit is set. Example: fix subnet
- `search_commit` (`string`, optional): Commit SHA the run used. Example: 7d0e1b5
- `search_user` (`string`, optional): VCS username that triggered the run. Example: octocat

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_state_versions_list`

List State Versions · Read-only

List the state versions of one HCP Terraform workspace, newest first, identified by organization and workspace name.
Returns state versions with id (sv-...), serial, status, created-at, resource and provider details and download URLs.
Use terraform_state_versions_list for state history. Use terraform_workspace_current_state_version_get for the latest only.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): Name of the organization that owns the workspace. Example: my-org
- `workspace_name` (`string`, required): Name of the workspace whose state versions to list. Example: networking-prod
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `status` (`string`, optional): Only state versions with this status: pending, finalized or discarded. Example: finalized. One of: `pending`, `finalized`, `discarded`.

Example input: `{"organization_name":"<organization_name>","workspace_name":"<workspace_name>"}`

### `terraform_teams_list`

List Teams · Read-only

List the teams in an HCP Terraform organization, optionally searching by name.
Returns teams with id (team-...), name, visibility, user count and organization access settings.
Use terraform_teams_list to find team IDs and members' access.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `filter_names` (`string`, optional): Exact team name, or several comma-separated names, to return. Example: owners,platform
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `q` (`string`, optional): Case-insensitive search on team name. Example: platform

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_variable_sets_list`

List Variable Sets · Read-only

List the variable sets in an HCP Terraform organization, optionally searching by name.
Returns variable sets with id (varset-...), name, description, global and priority flags, and the workspaces, projects and variables they apply to.
Use terraform_variable_sets_list for shared variables. Use terraform_workspace_variables_list for variables set on one workspace.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `q` (`string`, optional): Search variable sets by name. Example: aws-credentials

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_workspace_current_state_outputs_list`

List Current State Outputs · Read-only

List the output values from the current state of an HCP Terraform workspace.
Returns outputs with name, type, value and sensitive flag; sensitive values come back as null. Returns 503 while outputs are still being processed, so retry later.
Use terraform_workspace_current_state_outputs_list to read outputs such as endpoints or IDs. It only needs read-outputs permission.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_current_state_version_get`

Get Current State Version · Read-only

Get the current state version of an HCP Terraform workspace.
Returns its id (sv-...), serial, Terraform version, resource list with counts, and short-lived hosted-state-download-url and hosted-json-state-download-url links. Needs permission to read state versions.
Use terraform_workspace_current_state_version_get for the latest state. Use terraform_workspace_current_state_outputs_list for output values only.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_get`

Get Workspace · Read-only

Get one HCP Terraform workspace by ID.
Returns its settings (execution mode, Terraform version, auto-apply, working directory, VCS repo), lock state, resource count and relationships such as current run and project.
Use terraform_workspace_get when you have the ws- ID. Use terraform_workspace_get_by_name when you have the organization and workspace name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_get_by_name`

Get Workspace by Name · Read-only

Get one HCP Terraform workspace by organization and workspace name.
Returns the same workspace record as terraform_workspace_get, including its ws- ID.
Use terraform_workspace_get_by_name to turn a workspace name into its ID. Use terraform_workspace_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `workspace_name` (`string`, required): Exact workspace name (letters, numbers, - and _). Example: networking-prod

Example input: `{"organization_name":"<organization_name>","workspace_name":"<workspace_name>"}`

### `terraform_workspace_variables_list`

List Workspace Variables · Read-only

List the Terraform and environment variables set directly on an HCP Terraform workspace.
Returns variables with id (var-...), key, value (null when sensitive), category, hcl and sensitive flags.
Use terraform_workspace_variables_list before updating or deleting a variable. Use terraform_variable_sets_list for shared variable sets.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspaces_list`

List Workspaces · Read-only

List the workspaces in an HCP Terraform organization, with name search, tag filters, project filter and sorting.
Returns workspace records with id (ws-...), name, execution mode, Terraform version, locked state, resource count and latest run, plus pagination meta.
Use terraform_workspaces_list to search or browse. Use terraform_workspace_get or terraform_workspace_get_by_name for one workspace.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `current_run_status` (`string`, optional): Return only workspaces whose current run has this status, such as planned, applied, errored or policy_checked. Example: errored
- `page_number` (`integer`, optional): Page number to return, starting at 1. Defaults to the first page. Example: 2
- `page_size` (`integer`, optional): Number of results per page, 1 to 100. Defaults to 20. Example: 50
- `project_id` (`string`, optional): Return only workspaces in this project (prj-...). Example: prj-WsVcWRr7SSxRDEDx
- `search_exclude_tags` (`string`, optional): Leave out workspaces that have any of these flat string tags, comma-separated. Example: deprecated
- `search_name` (`string`, optional): Fuzzy search on workspace name. Example: networking
- `search_tags` (`string`, optional): Return only workspaces that have all of these flat string tags, comma-separated. Example: networking,prod
- `search_wildcard_name` (`string`, optional): Workspace name pattern with * at the start, end or both. Example: *-prod
- `sort` (`string`, optional): Sort by name, current-run.created-at or latest-change-at; prefix with - to reverse. Example: -current-run.created-at. One of: `name`, `-name`, `current-run.created-at`, `-current-run.created-at`, `latest-change-at`, `-latest-change-at`.

Example input: `{"organization_name":"<organization_name>"}`

### `terraform_project_create`

Create Project · Write

Create a project in an HCP Terraform organization to group workspaces.
Returns the new project with its id (prj-...).
Use terraform_project_create for a new project. Use terraform_workspace_create with project_id to add workspaces to it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Project name: 3 to 40 characters of letters, numbers, spaces, - and _, not starting or ending with a space. Example: networking
- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `default_execution_mode` (`string`, optional): Default execution mode for workspaces in this project: remote, local or agent. Defaults to remote. agent also needs a default agent pool, which this tool does not set. Example: remote. One of: `remote`, `local`, `agent`.
- `description` (`string`, optional): Project description, up to 256 characters. Example: Shared network infrastructure

Example input: `{"name":"<name>","organization_name":"<organization_name>"}`

### `terraform_run_apply`

Apply Run · Write

Confirm and apply a run that is waiting for confirmation after its plan (status planned, cost_estimated or policy_checked).
Returns 202 with no body; the apply is queued. Fails with 409 if the run is not waiting for confirmation.
Use terraform_run_apply to approve a plan. Use terraform_run_discard to reject it. Needs a user or team token.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `run_id` (`string`, required): ID of the run to apply, starting with run-. Use terraform_runs_list to find it. Example: run-CZcmD7eagjhyX0vN
- `comment` (`string`, optional): Optional comment recorded with the apply. Example: Approved after review

Example input: `{"run_id":"<run_id>"}`

### `terraform_run_cancel`

Cancel Run · Write

Interrupt a run that is currently planning or applying, like pressing Ctrl+C.
Returns 202 with no body. Fails with 409 if the run is not planning or applying.
Use terraform_run_cancel for an in-progress run. Use terraform_run_discard for a run waiting for confirmation.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `run_id` (`string`, required): ID of the run to cancel, starting with run-. Use terraform_runs_list to find it. Example: run-CZcmD7eagjhyX0vN
- `comment` (`string`, optional): Optional comment recorded with the cancel. Example: Approved after review

Example input: `{"run_id":"<run_id>"}`

### `terraform_run_create`

Create Run · Write

Queue a new run (plan, and apply if confirmed or auto-applied) in an HCP Terraform workspace using its latest or a given configuration version.
Returns the new run with id (run-...) and status pending.
Use terraform_run_create to plan or destroy. Use terraform_run_apply to confirm a run waiting for approval. Needs a user or team token, not an organization token.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace to run in, starting with ws-. Example: ws-SihZTyXKfNXUWuUa
- `allow_empty_apply` (`boolean`, optional): Allow applying even when the plan has no changes, for example to upgrade state after a Terraform version change. Example: false
- `auto_apply` (`boolean`, optional): Apply automatically when the plan succeeds. Defaults to the workspace's auto-apply setting. Example: false
- `configuration_version_id` (`string`, optional): Configuration version to run (cv-...). Defaults to the workspace's latest. Example: cv-n4XQPBa2QnecZJ4G
- `is_destroy` (`boolean`, optional): true to plan destroying all managed resources. Cannot be combined with refresh_only. Example: false
- `message` (`string`, optional): Message shown on the run. Defaults to "Queued manually via the Terraform Enterprise API". Example: Scale web tier to 3 replicas
- `plan_only` (`boolean`, optional): true for a speculative plan that cannot be applied. Example: true
- `refresh_only` (`boolean`, optional): true to only refresh state without changing resources. Cannot be combined with is_destroy. Example: false
- `replace_addrs` (`array`, optional): Resource addresses passed to -replace. Example: ["aws_instance.web"]
- `target_addrs` (`array`, optional): Resource addresses passed to -target. Example: ["aws_instance.web"]
- `terraform_version` (`string`, optional): Terraform version for this run; only valid for plan-only runs. Example: 1.10.0
- `variables` (`array`, optional): Run-specific variable values; each item has key and value, where value is an HCL literal (strings need inner quotes). Example: [{"key": "replicas", "value": "3"}, {"key": "env", "value": "\"prod\""}]

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_run_discard`

Discard Run · Write

Discard a run that is waiting for confirmation or a policy override, so it is not applied.
Returns 202 with no body. Fails with 409 if the run cannot be discarded.
Use terraform_run_discard to reject a plan. Use terraform_run_cancel to stop a run that is planning or applying.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `run_id` (`string`, required): ID of the run to discard, starting with run-. Use terraform_runs_list to find it. Example: run-CZcmD7eagjhyX0vN
- `comment` (`string`, optional): Optional comment recorded with the discard. Example: Approved after review

Example input: `{"run_id":"<run_id>"}`

### `terraform_workspace_create`

Create Workspace · Write

Create a workspace in an HCP Terraform organization, optionally in a project and connected to a VCS repository.
Returns the new workspace with its id (ws-...).
Use terraform_workspace_create for a new workspace. Use terraform_workspace_update to change one that exists.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Workspace name, unique in the organization; letters, numbers, - and _ only. Example: networking-prod
- `organization_name` (`string`, required): The organization name (not ID), as shown in the HCP Terraform URL app.terraform.io/app/<organization>. Use terraform_organizations_list to find it. Example: my-org
- `agent_pool_id` (`string`, optional): Agent pool ID (apool-...); required when execution_mode is agent and not allowed otherwise. Example: apool-yoGUFz5zcRMMz53i
- `allow_destroy_plan` (`boolean`, optional): Whether destroy plans can be queued on the workspace. Defaults to true on create. Example: true
- `auto_apply` (`boolean`, optional): Whether successful plans from VCS, UI or CLI runs apply automatically. Example: false
- `description` (`string`, optional): Workspace description. Example: Production VPC and subnets
- `execution_mode` (`string`, optional): Where runs execute: remote (HCP Terraform), local (state storage only) or agent (needs agent_pool_id). Example: remote. One of: `remote`, `local`, `agent`.
- `project_id` (`string`, optional): Project to create the workspace in (prj-...). Defaults to the organization's default project. Example: prj-WsVcWRr7SSxRDEDx
- `terraform_version` (`string`, optional): Terraform version or version constraint for the workspace, such as 1.9.5 or ~> 1.9.0. Defaults to the latest release on create. Example: 1.9.5
- `vcs_repo` (`object`, optional): VCS repository settings. Needs identifier (org/repo) and either oauth-token-id (ot-...) or github-app-installation-id (ghain-...); optional branch, ingress-submodules and tags-regex. Keys use hyphens. Example: {"identifier": "acme/infra", "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", "branch": "main"}
- `working_directory` (`string`, optional): Relative path in the repository where Terraform runs. Example: environments/prod

Example input: `{"name":"<name>","organization_name":"<organization_name>"}`

### `terraform_workspace_lock`

Lock Workspace · Write

Lock an HCP Terraform workspace so no new runs can start until it is unlocked.
Returns the workspace with locked true. Fails with 409 if it is already locked.
Use terraform_workspace_lock before maintenance. Use terraform_workspace_unlock to release it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace to lock, starting with ws-. Example: ws-SihZTyXKfNXUWuUa
- `reason` (`string`, optional): Why the workspace is locked, shown to other users. Example: Maintenance window

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_unlock`

Unlock Workspace · Write

Unlock an HCP Terraform workspace that the same user or team locked.
Returns the workspace with locked false. Fails with 409 if it is not locked or was locked by someone else.
Use terraform_workspace_unlock after terraform_workspace_lock.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace to unlock, starting with ws-. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_update`

Update Workspace · Write

Update settings of an HCP Terraform workspace by ID; only the fields you pass change.
Returns the updated workspace.
Use terraform_workspace_update to rename or reconfigure a workspace. Use terraform_workspace_lock to block runs instead.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace to update, starting with ws-. Example: ws-SihZTyXKfNXUWuUa
- `agent_pool_id` (`string`, optional): Agent pool ID (apool-...); required when execution_mode is agent and not allowed otherwise. Example: apool-yoGUFz5zcRMMz53i
- `allow_destroy_plan` (`boolean`, optional): Whether destroy plans can be queued on the workspace. Defaults to true on create. Example: true
- `auto_apply` (`boolean`, optional): Whether successful plans from VCS, UI or CLI runs apply automatically. Example: false
- `description` (`string`, optional): Workspace description. Example: Production VPC and subnets
- `execution_mode` (`string`, optional): Where runs execute: remote (HCP Terraform), local (state storage only) or agent (needs agent_pool_id). Example: remote. One of: `remote`, `local`, `agent`.
- `name` (`string`, optional): New workspace name; letters, numbers, - and _ only. Renaming changes the workspace's URL. Example: networking-production
- `terraform_version` (`string`, optional): Terraform version or version constraint for the workspace, such as 1.9.5 or ~> 1.9.0. Defaults to the latest release on create. Example: 1.9.5
- `vcs_repo` (`object`, optional): VCS repository settings. Needs identifier (org/repo) and either oauth-token-id (ot-...) or github-app-installation-id (ghain-...); optional branch, ingress-submodules and tags-regex. Keys use hyphens. Example: {"identifier": "acme/infra", "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", "branch": "main"}
- `working_directory` (`string`, optional): Relative path in the repository where Terraform runs. Example: environments/prod

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_variable_create`

Create Workspace Variable · Write

Create a Terraform or environment variable on an HCP Terraform workspace.
Returns the new variable with its id (var-...).
Use terraform_workspace_variable_create for a new key. Use terraform_workspace_variable_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `category` (`string`, required): terraform for a Terraform input variable, env for an environment variable. Example: terraform. One of: `terraform`, `env`.
- `key` (`string`, required): Variable name. Example: region
- `workspace_id` (`string`, required): ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa
- `description` (`string`, optional): Variable description. Example: AWS region
- `hcl` (`boolean`, optional): true to evaluate the value as HCL (lists, maps); no effect on environment variables. Example: false
- `sensitive` (`boolean`, optional): true to make the value write-only; it is never shown again. Example: false
- `value` (`string`, optional): Variable value. HCL values are evaluated as HCL when hcl is true. Example: us-east-1

Example input: `{"category":"terraform","key":"<key>","workspace_id":"<workspace_id>"}`

### `terraform_workspace_variable_update`

Update Workspace Variable · Write

Update a variable on an HCP Terraform workspace; only the fields you pass change.
Returns the updated variable.
Use terraform_workspace_variable_update to change a value. Get the variable ID from terraform_workspace_variables_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `variable_id` (`string`, required): ID of the variable, starting with var-. Example: var-EavQ1LztoRTQHSNT
- `workspace_id` (`string`, required): ID of the workspace that owns the variable, starting with ws-. Example: ws-SihZTyXKfNXUWuUa
- `category` (`string`, optional): terraform or env. Example: terraform. One of: `terraform`, `env`.
- `description` (`string`, optional): Variable description. Example: AWS region
- `hcl` (`boolean`, optional): true to evaluate the value as HCL (lists, maps); no effect on environment variables. Example: false
- `key` (`string`, optional): New variable name. Example: aws_region
- `sensitive` (`boolean`, optional): true to make the value write-only; it is never shown again. Example: false
- `value` (`string`, optional): Variable value. HCL values are evaluated as HCL when hcl is true. Example: us-east-1

Example input: `{"variable_id":"<variable_id>","workspace_id":"<workspace_id>"}`

### `terraform_workspace_safe_delete`

Safe Delete Workspace · Destructive

Delete an HCP Terraform workspace only if it manages no resources.
Returns no content on success; returns 409 if the workspace still manages resources (destroy them first with terraform_run_create and is_destroy).
Use terraform_workspace_safe_delete to remove an empty workspace. It cannot be undone.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `workspace_id` (`string`, required): ID of the workspace to delete, starting with ws-. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"workspace_id":"<workspace_id>"}`

### `terraform_workspace_variable_delete`

Delete Workspace Variable · Destructive

Delete a variable from an HCP Terraform workspace.
Returns no content on success.
Use terraform_workspace_variable_delete to remove a key. Get the variable ID from terraform_workspace_variables_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `variable_id` (`string`, required): ID of the variable to delete, starting with var-. Example: var-EavQ1LztoRTQHSNT
- `workspace_id` (`string`, required): ID of the workspace that owns the variable, starting with ws-. Example: ws-SihZTyXKfNXUWuUa

Example input: `{"variable_id":"<variable_id>","workspace_id":"<workspace_id>"}`

## Related

Other Developer Tools connectors ([all 200](/agentkit/connectors/?category=developer-tools)):

- [GitHub](/agentkit/connectors/github/): Scalekit connector, OAuth, 217 tools
- [Datadog](/agentkit/connectors/datadog/): Scalekit connector, API key, 105 tools
- [Linear](/agentkit/connectors/linear/): Scalekit connector, OAuth, 64 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
