Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to HCP Terraform

Scalekit connector
Open markdown

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.

Tools
30
What they doRead · write · destructive
17 · 11 · 217 read11 write2 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .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.

  4. Authorize a user and make your first call

    quickstart.mts
    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)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their HCP Terraform credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • terraform_organization_getGet one HCP Terraform organization by name.Read-only

    Get Organization

    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.

    Inputs

    organization_namestringrequired
    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
  • terraform_organization_runs_listList runs across all workspaces in an HCP Terraform organization, with workspace, status and text filters.Read-only

    List Organization Runs

    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.

    Inputs

    organization_namestringrequired
    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_operationstring
    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_sourcestring
    Comma-separated run sources: tfe-ui, tfe-api, tfe-configuration-version. Example: tfe-api
    filter_statusstring
    Comma-separated run statuses to return, such as planned,errored,applied,policy_checked,discarded. Example: planned,errored
    filter_status_groupstring
    One status group: non_final (running or waiting), final (finished) or discardable. Example: non_finalone of non_finalfinaldiscardable
    filter_timeframestring
    A year such as 2025, or year for the past year. Example: 2025
    filter_workspace_namesstring
    Comma-separated workspace names to include. Example: networking-prod,app-prod
    page_numberinteger
    Page number to return, starting at 1. Defaults to the first page. Example: 2
    page_sizeinteger
    Number of results per page, 1 to 100. Defaults to 20. Example: 50
    search_basicstring
    Matches VCS username, commit SHA, run ID or run message; ignored if search_user or search_commit is set. Example: fix subnet
    search_commitstring
    Commit SHA the run used. Example: 7d0e1b5
    search_userstring
    VCS username that triggered the run. Example: octocat
  • terraform_organizations_listList the HCP Terraform organizations the token can access, optionally searching by name or notification email.Read-only

    List Organizations

    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.

    Inputs

    page_numberinteger
    Page number to return, starting at 1. Defaults to the first page. Example: 2
    page_sizeinteger
    Number of results per page, 1 to 100. Defaults to 20. Example: 50
    qstring
    Search string that matches organization names and notification emails. Takes precedence over q_email and q_name. Example: acme
    q_emailstring
    Search string matched against the organization notification email only. Example: ops@acme.com
    q_namestring
    Search string matched against the organization name only. Example: acme-prod
  • terraform_plan_getGet one HCP Terraform plan by ID.Read-only

    Get Plan

    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.

    Inputs

    plan_idstringrequired
    ID of the plan, starting with plan-. Find it in a run's relationships.plan.data.id. Example: plan-8F5JFydVYAmtTjET
  • terraform_project_getGet one HCP Terraform project by ID.Read-only

    Get Project

    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.

    Inputs

    project_idstringrequired
    ID of the project, starting with prj-. Example: prj-WsVcWRr7SSxRDEDx
  • terraform_projects_listList the projects in an HCP Terraform organization, optionally searching by name.Read-only

    List Projects

    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.

    Inputs

    organization_namestringrequired
    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_namesstring
    Exact project name, or several comma-separated names, to return (case-insensitive). Example: Default Project,networking
    page_numberinteger
    Page number to return, starting at 1. Defaults to the first page. Example: 2
    page_sizeinteger
    Number of results per page, 1 to 100. Defaults to 20. Example: 50
    qstring
    Case-insensitive search on project name. Ignored when filter_names is set. Example: networking
    sortstring
    Sort order: name, or -name for reverse alphabetical. Example: -nameone of name-name
  • terraform_run_getGet one HCP Terraform run by ID.Read-only

    Get Run

    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.

    Inputs

    run_idstringrequired
    ID of the run to get, starting with run-. Use terraform_runs_list to find it. Example: run-CZcmD7eagjhyX0vN
  • terraform_runs_listList runs in one HCP Terraform workspace, newest first, with status, operation and text filters.Read-only

    List Workspace Runs

    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.

    Inputs

    workspace_idstringrequired
    ID of the workspace, starting with ws-. Use terraform_workspaces_list or terraform_workspace_get_by_name to find it. Example: ws-SihZTyXKfNXUWuUa
    filter_operationstring
    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_sourcestring
    Comma-separated run sources: tfe-ui, tfe-api, tfe-configuration-version. Example: tfe-api
    filter_statusstring
    Comma-separated run statuses to return, such as planned,errored,applied,policy_checked,discarded. Example: planned,errored
    filter_status_groupstring
    One status group: non_final (running or waiting), final (finished) or discardable. Example: non_finalone of non_finalfinaldiscardable
    filter_timeframestring
    A year such as 2025, or year for the past year. Example: 2025
    page_numberinteger
    Page number to return, starting at 1. Defaults to the first page. Example: 2
    page_sizeinteger
    Number of results per page, 1 to 100. Defaults to 20. Example: 50
    search_basicstring
    Matches VCS username, commit SHA, run ID or run message; ignored if search_user or search_commit is set. Example: fix subnet
    search_commitstring
    Commit SHA the run used. Example: 7d0e1b5
    search_userstring
    VCS username that triggered the run. Example: octocat