---
name: hcl
displayName: HCL / Terraform Config Reader & Converter
description: Read, inspect, and convert HCL and Terraform (.tf, .hcl) config
  files to JSON or CSV. Use when opening Terraform configs, extracting
  resources, or exporting structured data.
tags:
  - hcl
  - terraform
  - config
  - iac
  - json
  - conversion
  - extractor
capabilities:
  - ReadHcl
  - InspectBlocks
  - ConvertToJson
  - ExtractResources
  - ConvertToCsv
representativeQueries:
  - Read a .tf file and show me the resources
  - Convert HCL config to JSON
  - Extract all resources from a Terraform file
  - What blocks are defined in this .hcl file?
  - Export Terraform config to CSV
version: 0.1.0
tier: curated
---

# HCL / Terraform Config Reader & Converter

Read, inspect, and convert HCL and Terraform configuration files (`.tf`, `.hcl`) using `python-hcl2`. Extracts block structure, resource inventories, and exports data to JSON or CSV without requiring the Terraform CLI.

## When to use

Use this skill when you need to:
- Open a `.tf` or `.hcl` file and display its contents in a readable format
- List all resource, data source, variable, or output blocks defined in a config
- Convert HCL config data to JSON for downstream processing or diffing
- Export a resource inventory to CSV for auditing or reporting
- Inspect provider configurations, module calls, or locals in a Terraform root

## Steps

1. **Locate the file.** Confirm the `.tf` or `.hcl` path exists and is readable.
2. **Inspect blocks.** Run `scripts/hcl_convert.py <file> --blocks` to print all top-level block types and their labels.
3. **Review resources.** Run `scripts/hcl_convert.py <file> --resources` for a flat inventory of all `resource` blocks (type + name pairs).
4. **Convert or export.** Run `scripts/hcl_convert.py <file> --json` for full JSON output or `--csv` for a flat CSV of all resource/data blocks.
5. **Handle a directory.** Pass a directory path to scan all `.tf` files in it and merge results into a single output.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| `ReadHcl` | READ | .tf / .hcl file | `scripts/hcl_convert.py` |
| `InspectBlocks` | READ | block type inventory | `scripts/hcl_convert.py --blocks` |
| `ExtractResources` | READ | resource block list | `scripts/hcl_convert.py --resources` |
| `ConvertToJson` | READ | JSON export | `scripts/hcl_convert.py --json` |
| `ConvertToCsv` | READ | CSV export | `scripts/hcl_convert.py --csv` |

## Output

- `--blocks`: newline-delimited `block_type: [first_label, ...]` summary to stdout (for `resource` and `data` blocks the first label is the resource type, e.g. `aws_s3_bucket`; instance names are not shown)
- `--resources`: flat list of `resource_type.resource_name` identifiers to stdout
- `--json`: full parsed HCL as a JSON object to stdout
- `--csv`: CSV with columns `block_type, resource_type, name` to stdout (one row per resource/data block)

Redirect to a file: `python3 scripts/hcl_convert.py main.tf --json > main.json`

## Context

- HCL expressions (`var.foo`, `"${...}"`, function calls) are returned as raw strings — they are not evaluated.
- Multi-file Terraform roots: pass a directory to process all `.tf` files together; individual file parsing misses cross-file references.
- Block types vary by tool: Terraform uses `resource`, `data`, `variable`, `output`, `locals`, `provider`, `module`, `terraform`; other HCL tools (Packer, Vault) have different schemas.
- `python-hcl2` supports HCL2 (Terraform 0.12+). Legacy HCL1 (Terraform 0.11 and older) is not supported.
- Nested blocks (e.g., `lifecycle`, `connection`, `provisioner`) appear as nested dicts in the parsed output.

## Notes

- Requires `python-hcl2` (`pip install python-hcl2`). The script prints a one-line install hint and exits non-zero if the library is missing.
- The script writes only to stdout; the caller controls destination files.
- For diffing two Terraform roots, convert both to JSON and use `diff` or `jq` for comparison.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `hcl_blocks`, `hcl_resources`, `hcl_to_json`, `hcl_to_csv`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).