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

# Using Terraform CLI

> Run Terraform commands locally against your Nuon-managed sandbox and component workspaces.

The Nuon dashboard provides a **Use Terraform CLI** option on both the Sandbox and Terraform Component detail pages. This lets you run Terraform commands locally against the remote state managed by Nuon. It's useful for debugging, inspecting resources, importing state, or running targeted plans.

## Prerequisites

<Steps>
  <Step title="Install the Nuon CLI">
    Install the Nuon CLI if you haven't already:

    ```bash theme={null}
    brew install nuonco/tap/nuon
    ```

    Authenticate with your account:

    ```bash theme={null}
    nuon auth login
    ```
  </Step>

  <Step title="Match the Terraform version">
    You must use the **same Terraform version** configured for the sandbox or component. The version is displayed on the configuration card in the dashboard.

    For sandboxes, this is the `terraform_version` in your `sandbox.toml`. For components, it's the `terraform_version` in the component's `.toml` config.

    Terraform is deprecated on `brew`. Consider using Terraform version manager `tfenv` to install and use multiple Terraform versions locally. You can install it with:

    ```bash theme={null}
    brew update
    brew install tfenv
    ```

    List remote versions, install specific versions, list versions, and globally select a version

    ```bash theme={null}
    tfenv list-remote
    tfenv install 1.13.5
    tfenv install 1.11.3
    tfenv list
    tfenv use 1.13.5
    ```

    Verify your local version matches:

    ```bash theme={null}
    terraform version
    ```

    <Warning>
      Running a different Terraform version can corrupt state or produce unexpected plan diffs. Use a version manager like [tfenv](https://github.com/tfutils/tfenv) or [asdf](https://github.com/asdf-vm/asdf) to switch versions easily.
    </Warning>
  </Step>

  <Step title="Navigate to the Terraform source code">
    You must run Terraform commands from within the **same Terraform module directory** that the sandbox or component is configured to use. This is the directory containing your `.tf` files.

    For example, if your sandbox is configured with:

    ```toml sandbox.toml theme={null}
    [public_repo]
    repo      = "nuonco/aws-eks-sandbox"
    directory = "."
    branch    = "main"
    ```

    Then clone and enter that repo:

    ```bash theme={null}
    git clone https://github.com/nuonco/aws-eks-sandbox.git
    cd aws-eks-sandbox
    ```

    For a component configured with a subdirectory:

    ```toml components/database.toml theme={null}
    [public_repo]
    repo      = "your-org/your-infra"
    directory = "modules/database"
    branch    = "main"
    ```

    Navigate to that subdirectory:

    ```bash theme={null}
    cd modules/database
    ```
  </Step>
</Steps>

## Setting Up the Backend

Click the **\{} Use Terraform CLI** button on the lower right part of Sandbox or Component detail page in the dashboard. This opens a modal, and click the Download button to retrieve a `nuon_backend.tf` file containing the HTTP backend configuration for that workspace.

The generated file looks like this:

```hcl nuon_backend.tf theme={null}
terraform {
  backend "http" {
    lock_method    = "POST"
    unlock_method  = "POST"
    address        = "https://api.nuon.co/v1/terraform-backend?workspace_id=<workspace_id>&org_id=<org_id>&token=undefined"
    lock_address   = "https://api.nuon.co/v1/terraform-workspaces/<workspace_id>/lock?org_id=<org_id>&token=undefined"
    unlock_address = "https://api.nuon.co/v1/terraform-workspaces/<workspace_id>/unlock?org_id=<org_id>&token=undefined"
  }
}
```

Download this file and place it in your Terraform module directory alongside the other `.tf` files.

## Set your Nuon API token

Retrieve your Nuon API token

```bash theme={null}
nuon orgs api-token
```

Replace the three token `undefined` blocks in `nuon_backend.tf` with your org's API token.

## Initializing Terraform

Initialize the backend:

```bash theme={null}
terraform init -reconfigure
```

The `-reconfigure` flag is required to switch Terraform's backend to the Nuon HTTP backend. After initialization, your local Terraform is connected to the remote workspace state.

<Note>
  `nuon orgs api-token` generates a short-lived API token scoped to your currently selected org. Make sure you've selected the correct org with `nuon orgs select` before running this command. The token is used to authenticate all Terraform backend requests (state, lock, and unlock).
</Note>

## Running Commands

Once initialized, you can run standard Terraform commands against the workspace:

```bash theme={null}
# View current state
terraform state list

# Inspect a specific resource
terraform state show <resource_address>

# Preview changes
terraform plan

# Apply changes
terraform apply

# Import an existing resource into state
terraform import <resource_address> <resource_id>
```

<Warning>
  Running `terraform apply` locally will modify the live install infrastructure. Use caution and prefer `terraform plan` for inspection.
</Warning>

## Unlocking State

If a Terraform operation is interrupted (e.g., a network failure during apply), the workspace state may remain locked. You can unlock it from the dashboard using the **Unlock Terraform state** button on the Sandbox or Component detail page.

<Note>
  Only force unlock a workspace if you are certain no other operation is actively running. Force unlocking a workspace in use by a running job may cause state corruption.
</Note>

## Viewing State in the Dashboard

The dashboard displays the current Terraform state for both sandboxes and components, organized into two tabs:

* **Outputs** - all Terraform outputs and their current values
* **Resources** - all managed resources with their type, provider, mode, and attribute values

This state view updates after each successful sandbox run or component deploy.