# Develop Terraform Locally

Use this guide when you need to run `terraform plan` or `tofu plan` locally against infrastructure managed by Bluebricks, for debugging or state inspection.

{% hint style="info" %}
For background on how Bluebricks manages Terraform state and artifacts, see [Terraform/OpenTofu](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages/artifacts-overview/terraform-open-tofu) in the main documentation.
{% endhint %}

## Before you begin

* At least one blueprint is deployed to a Bluebricks environment. If you haven't deployed one yet, follow the [Quick Start](https://docs.bluebricks.co/bluebricks-documentation/getting-started/quick-start) tutorial
* The Bricks CLI is installed and authenticated (`bricks whoami` returns your user)
* You have access to the git repository containing the Terraform or OpenTofu source code

{% hint style="warning" %}
This procedure works against your **live remote state**. Review all planned changes carefully before applying anything. Use this for debugging and inspection, not production changes.
{% endhint %}

## Step-by-step

{% stepper %}
{% step %}

#### Navigate to the source code directory

Clone or open your artifact's git repository and navigate to the directory containing your `.tf` files:

```
.                          <-- Artifact root directory
├── bricks.json
└── src
    └── terraform          <-- Navigate here
        ├── locals.tf
        ├── main.tf
        ├── outputs.tf
        ├── variables.tf
        └── vpc.tf
```

{% endstep %}

{% step %}

#### Run `bricks bp state-config`

Replace `<ENVIRONMENT_SLUG>` with your environment's slug (visible in the Bluebricks app on the environment page):

```bash
bricks bp state-config <ENVIRONMENT_SLUG>
```

This generates two files in your current directory:

* **`backend.tf`**: remote state backend configuration (contains a temporary JWT)
* **`bbx-terraform-temp.auto.tfvars`**: properties from the last successful run (if applicable)
  {% endstep %}

{% step %}

#### Review the generated files

Open `backend.tf` and `bbx-terraform-temp.auto.tfvars` and confirm they match your expectations before proceeding.
{% endstep %}

{% step %}

#### Initialize and plan

Run `terraform init` (or `tofu init`) followed by `terraform plan` (or `tofu plan`):

```bash
terraform init
terraform plan
```

Confirm your local environment matches the deployed state before making any changes.
{% endstep %}

{% step %}

#### Clean up before publishing

The `backend.tf` file contains your personal JWT token. Remove it before publishing the artifact:

```bash
rm backend.tf
```

To prevent accidental publishing, add `backend.tf` to the `.bricksignore` file in the artifact root directory:

```bash
echo "backend.tf" >> .bricksignore
```

{% endstep %}
{% endstepper %}

## Troubleshooting

**Resources keep being recreated**: your local environment settings (region, project, or account) likely differ from your Terraform configuration. Make sure local environment variables match. For example, set the AWS region:

```bash
export AWS_REGION=eu-north-1
```

Or add explicit provider configuration:

```hcl
provider "aws" {
  region = var.aws_region
}
```

**`bricks bp state-config` fails to create files**: the CLI is not authenticated. Run `bricks login` and try again.

**JWT expired during a long session**: the token in `backend.tf` expires after a period. Re-run `bricks bp state-config <ENVIRONMENT_SLUG>` to generate a fresh token.

## Related

* [Terraform/OpenTofu overview](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages/artifacts-overview/terraform-open-tofu) (Docs)
* [Bricks CLI Overview](https://docs.bluebricks.co/bluebricks-documentation/bricks-cli/bricks-cli) (Docs)
* [Packages & Blueprints Troubleshooting](/docs/help/troubleshooting/packages.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/help/guides/develop-terraform-locally.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.