download_state_file
Retrieve Terraform Cloud state files in raw or JSON format for specific state versions to manage infrastructure configuration and track changes.
Instructions
Download the state file content.
Retrieves the raw state file or JSON formatted state file for a specific state version.
API endpoint: Uses the hosted URLs from GET /state-versions/:state_version_id
Args: state_version_id: The ID of the state version (format: "sv-xxxxxxxx") json_format: Whether to download the JSON formatted state (default: False)
Returns: The raw state file content or JSON formatted state content
See: docs/tools/state_versions.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| state_version_id | Yes | ||
| json_format | No |
Implementation Reference
- The main handler function that executes the tool logic: validates input, fetches state version details to get download URL, handles JSON or raw format, and downloads the state file content using api_request.
async def download_state_file( state_version_id: str, json_format: bool = False ) -> APIResponse: """Download the state file content. Retrieves the raw state file or JSON formatted state file for a specific state version. API endpoint: Uses the hosted URLs from GET /state-versions/:state_version_id Args: state_version_id: The ID of the state version (format: "sv-xxxxxxxx") json_format: Whether to download the JSON formatted state (default: False) Returns: The raw state file content or JSON formatted state content See: docs/tools/state_versions.md for reference documentation """ # Validate parameters params = StateVersionRequest(state_version_id=state_version_id) # First get state version details to get the download URL state_version = await api_request(f"state-versions/{params.state_version_id}") # Determine which URL to use based on format request url_attr = ( "hosted-json-state-download-url" if json_format else "hosted-state-download-url" ) download_url = state_version.get("data", {}).get("attributes", {}).get(url_attr) # Check if URL is available if not download_url: if json_format: return { "error": "JSON state download URL not available. This may be because the state was not created with Terraform 1.3+" } else: return {"error": "State download URL not available for this state version"} # Use the enhanced api_request to fetch state from the external URL return await api_request(download_url, external_url=True, accept_text=True) - Pydantic model for input validation of state_version_id parameter used in the handler.
class StateVersionRequest(APIRequest): """Request model for retrieving a state version. Used to validate the state version ID parameter for API requests. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions See: docs/models/state_versions.md for reference """ state_version_id: str = Field( ..., description="The ID of the state version to retrieve", pattern=r"^sv-[a-zA-Z0-9]{16}$", # Standard state version ID pattern ) - terraform_cloud_mcp/server.py:117-117 (registration)Registers the download_state_file tool function with the MCP framework.
mcp.tool()(state_versions.download_state_file)