create_run
Initiate a Terraform run to deploy, update, or destroy infrastructure in a specified workspace. Configure parameters like auto-apply, destroy mode, or resource targeting to manage changes efficiently.
Instructions
Create a run in a workspace
Copy
Creates a new Terraform run to trigger infrastructure changes through Terraform Cloud,
representing a single execution of plan and apply operations. The run queues in the
workspace and executes based on the workspace's execution mode and settings. Use this
to deploy new infrastructure, apply configuration changes, or destroy resources.
API endpoint: POST /runs
Args:
workspace_id: The workspace ID to execute the run in (format: "ws-xxxxxxxx")
params: Optional run configuration with:
- message: Description of the run's purpose
- is_destroy: Whether to destroy all resources managed by the workspace
- auto_apply: Whether to auto-apply after a successful plan
- refresh: Whether to refresh Terraform state before planning
- refresh_only: Only refresh the state without planning changes
- plan_only: Create a speculative plan without applying
- allow_empty_apply: Allow applying when there are no changes
- target_addrs: List of resource addresses to specifically target
- replace_addrs: List of resource addresses to force replacement
- variables: Run-specific variables that override workspace variables
- terraform_version: Specific Terraform version to use for this run
- save_plan: Save the plan for later execution
- debugging_mode: Enable extended debug logging
Returns:
The created run details with ID, status, configuration information,
workspace relationship, and links to associated resources
See:
docs/tools/run_tools.md for usage examples
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| workspace_id | Yes |
Input Schema (JSON Schema)
{
"$defs": {
"RunParams": {
"description": "Parameters for run operations without routing fields.\n\nThis model provides all optional parameters that can be used when creating runs,\nreusing the field definitions from BaseRunRequest.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run\n\nNote:\n All fields are inherited from BaseRunRequest.\n\nSee:\n docs/models/run_examples.md for usage examples",
"properties": {
"allow-config-generation": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to allow generating config for imports",
"title": "Allow-Config-Generation"
},
"allow-empty-apply": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to allow apply when there are no changes",
"title": "Allow-Empty-Apply"
},
"auto-apply": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to auto-apply the run when planned (defaults to workspace setting)",
"title": "Auto-Apply"
},
"debugging-mode": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Enable debug logging for this run",
"title": "Debugging-Mode"
},
"is-destroy": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this run should destroy all resources",
"title": "Is-Destroy"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Message to include with the run",
"title": "Message"
},
"plan-only": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this is a speculative, plan-only run",
"title": "Plan-Only"
},
"refresh": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether to refresh state before plan",
"title": "Refresh"
},
"refresh-only": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this is a refresh-only run",
"title": "Refresh-Only"
},
"replace-addrs": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Resource addresses to replace",
"title": "Replace-Addrs"
},
"save-plan": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to save the plan without becoming the current run",
"title": "Save-Plan"
},
"target-addrs": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Resource addresses to target",
"title": "Target-Addrs"
},
"terraform-version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Specific Terraform version (only valid for plan-only runs)",
"title": "Terraform-Version"
},
"variables": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/RunVariable"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Run-specific variables",
"title": "Variables"
}
},
"title": "RunParams",
"type": "object"
},
"RunVariable": {
"description": "Model for run-specific variables.\n\nRun variables are used to provide input values for a specific run,\nwhich override any workspace variables for that run only.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run\n\nSee:\n docs/models/run_examples.md for usage examples",
"properties": {
"key": {
"description": "Variable key",
"maxLength": 128,
"minLength": 1,
"title": "Key",
"type": "string"
},
"value": {
"description": "Variable value",
"maxLength": 256,
"title": "Value",
"type": "string"
}
},
"required": [
"key",
"value"
],
"title": "RunVariable",
"type": "object"
}
},
"properties": {
"params": {
"anyOf": [
{
"$ref": "#/$defs/RunParams"
},
{
"type": "null"
}
],
"default": null
},
"workspace_id": {
"title": "Workspace Id",
"type": "string"
}
},
"required": [
"workspace_id"
],
"title": "create_runArguments",
"type": "object"
}
You must be authenticated.
Other Tools from terraform-cloud-mcp
- apply_run
- cancel_run
- create_organization
- create_run
- create_workspace
- delete_organization
- delete_workspace
- discard_run
- force_cancel_run
- force_execute_run
- force_unlock_workspace
- get_account_details
- get_organization_details
- get_organization_entitlements
- get_run_details
- get_workspace_details
- list_organizations
- list_runs_in_organization
- list_runs_in_workspace
- list_workspaces
- lock_workspace
- safe_delete_workspace
- unlock_workspace
- update_organization
- update_workspace
Related Tools
- @severity1/terraform-cloud-mcp
- @severity1/terraform-cloud-mcp
- @severity1/terraform-cloud-mcp
- @severity1/terraform-cloud-mcp
- @severity1/terraform-cloud-mcp