> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read tfvars in a forma

> Reuse existing Terraform and OpenTofu .tfvars files inside a forma, so one set of inputs drives both tools during a migration.

formae can read Terraform and OpenTofu `.tfvars` files directly inside a
[forma](/documentation/concepts/forma). Existing variable files from a Terraform
or OpenTofu codebase can drive a formae deployment without conversion or
duplication, so the same inputs stay shared between both tools while you migrate.

The `terraform.readTFVars()` function parses an HCL-format `.tfvars` file and
returns its variables as a Pkl `Dynamic`, so you read values with dot notation.

## Read a tfvars file

<Steps>
  <Step title="Import the terraform extension">
    Add the import alongside your other Pkl imports at the top of the forma:

    ```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
    import "@formae/ext/terraform.pkl"
    ```
  </Step>

  <Step title="Read the file">
    Bind the parsed values to a local. The path is resolved relative to the
    forma file's directory, and absolute paths also work:

    ```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
    local vars = terraform.readTFVars("prod.tfvars")
    ```
  </Step>

  <Step title="Access values with dot notation">
    Given this `prod.tfvars`:

    ```hcl theme={"languages":{"custom":["/languages/pkl.json"]}}
    region         = "us-west-2"
    instance_count = 3
    enable_logging = true
    tags           = { Name = "web-server", Environment = "production" }
    zones          = ["us-west-2a", "us-west-2b"]
    ```

    the values come through as:

    ```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
    local vars = terraform.readTFVars("prod.tfvars")

    vars.region          // "us-west-2"
    vars.instance_count  // 3
    vars.enable_logging  // true
    vars.tags.Name       // "web-server"
    vars.zones           // List("us-west-2a", "us-west-2b")
    ```
  </Step>
</Steps>

## Example forma

This forma reads `env/prod.tfvars` and uses its values to set a
[target](/documentation/concepts/target) region and interpolate a queue name:

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
amends "@formae/forma.pkl"
import "@formae/formae.pkl"
import "@formae/ext/terraform.pkl"
import "@aws/aws.pkl"
import "@aws/sqs/queue.pkl"

local tfvars = terraform.readTFVars("env/prod.tfvars")

forma {
  new formae.Stack {
    label = "my-stack"
    description = "Stack using tfvars"
  }

  new formae.Target {
    label = "aws-target"
    config = new aws.Config {
      region = tfvars.region
    }
  }

  new queue.Queue {
    label = "my-queue"
    queueName = "app-\(tfvars.region)-queue"
  }
}
```

Apply it the same way as any other forma. formae shows the plan and asks you to
confirm before making changes:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae apply --mode reconcile prod.pkl
```

Use `--simulate` to preview the plan without applying, or `--yes` to skip the
confirmation prompt.

## Supported types

Values are mapped from HCL to Pkl types as follows:

| tfvars type       | Pkl type                   |
| ----------------- | -------------------------- |
| `"string"`        | `String`                   |
| `42`              | `Int`                      |
| `3.14`            | `Float`                    |
| `true` / `false`  | `Boolean`                  |
| `["a", "b"]`      | `List`                     |
| `{ key = "val" }` | `Dynamic` (dot-accessible) |
| `null`            | `Null`                     |
| Heredoc (`<<EOF`) | `String`                   |

## What is supported

<Note>
  `readTFVars` reads HCL-format `.tfvars` files. The `.tfvars.json` format is not
  supported, and the file extension must be `.tfvars`. Values must be literals:
  variable references and function calls inside the file are not evaluated.
</Note>

## See also

* [Forma](/documentation/concepts/forma): the file that declares your infrastructure.
* [Values](/documentation/concepts/values): how formae resolves values in a forma.
* [Create a target](/documentation/guides/create-a-target): configure the cloud account and region a forma deploys to.