Using Terraform CLI - Nuon documentation

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

Install the Nuon CLI

Install the Nuon CLI if you haven’t already:

brew install nuonco/tap/nuon

Authenticate with your account:

nuon auth login

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:

brew update
brew install tfenv

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

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:

terraform version

Running a different Terraform version can corrupt state or produce unexpected plan diffs. Use a version manager like tfenv or asdf to switch versions easily.

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:

sandbox.toml

[public_repo]
repo      = "nuonco/aws-eks-sandbox"
directory = "."
branch    = "main"

Then clone and enter that repo:

git clone https://github.com/nuonco/aws-eks-sandbox.git
cd aws-eks-sandbox

For a component configured with a subdirectory:

components/database.toml

[public_repo]
repo      = "your-org/your-infra"
directory = "modules/database"
branch    = "main"

Navigate to that subdirectory:

cd modules/database

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:

nuon_backend.tf

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

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:

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.

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).

Running Commands

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

# 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>

Running terraform apply locally will modify the live install infrastructure. Use caution and prefer terraform plan for inspection.

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.

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.

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.

​Prerequisites

​Setting Up the Backend

​Set your Nuon API token

​Initializing Terraform

​Running Commands

​Unlocking State

​Viewing State in the Dashboard

Prerequisites

Setting Up the Backend

Set your Nuon API token

Initializing Terraform

Running Commands

Unlocking State

Viewing State in the Dashboard