HCL Commands

The stategraph hcl command group works with Terraform HCL: listing addresses, evaluating expressions, converting between HCL and JSON, and importing HCL configuration into an existing state. Apart from hcl import, these commands run entirely locally and do not contact the server.

Commands

Command Description
stategraph hcl addresses List Terraform addresses from the HCL in the current directory
stategraph hcl eval Evaluate an HCL expression
stategraph hcl json Convert between HCL and JSON
stategraph hcl import Import HCL from the current directory into an existing state

stategraph hcl addresses

List the Terraform addresses declared in the HCL of the current directory, including resources inside local modules, module calls, and variables. Run it from your root module.

stategraph hcl addresses

Example

cd my-terraform-module
stategraph hcl addresses

Output (one address per line):

module.app.aws_instance.web
module.app
aws_subnet.public
aws_vpc.main
var.region

This is useful for building address globs for --force, --attach-files, or stategraph config files, and for quick scripting over a module's contents.

stategraph hcl eval

Evaluate an HCL expression and print the result. Reads the expression from the argument, or from stdin when the argument is omitted.

stategraph hcl eval [-e KEY=EXPR] [<expression>]

Arguments

Argument Required Description
<expression> No HCL expression to evaluate. If omitted, reads from stdin.

Options

Option Required Description
-e KEY=EXPR No Bind a variable in the environment. KEY is a dot-separated path (e.g., var.name); EXPR is an HCL expression evaluated using the environment built so far. Repeatable.

Examples

# Simple arithmetic
stategraph hcl eval '1 + 2'
# 3

# Terraform functions work
stategraph hcl eval 'upper("hello")'
# HELLO

stategraph hcl eval 'join("-", ["a", "b", "c"])'
# a-b-c

# Bind variables with -e, then reference them
stategraph hcl eval -e 'var.region="us-east-1"' '"bucket-${var.region}"'
# bucket-us-east-1

Use it to test interpolations and function calls without running a plan.

stategraph hcl json

Convert between HCL and JSON. Reads from stdin and writes to stdout. By default converts HCL to JSON in Terraform's JSON configuration syntax; --to-hcl converts the other way.

stategraph hcl json [--safe] [--to-hcl]

Options

Option Required Description
--to-hcl No Convert JSON to HCL instead of HCL to JSON
--safe No Use a schema-free encoding that preserves block structure instead of the Terraform JSON syntax

Examples

HCL to JSON:

stategraph hcl json < main.tf

{
  "resource": {
    "aws_s3_bucket": {
      "data": [ { "bucket": "my-data", "tags": { "env": "prod" } } ]
    }
  }
}

JSON back to HCL:

stategraph hcl json --to-hcl < main.tf.json

resource "aws_s3_bucket" "data" {
  bucket = "my-data"
}

With --safe, the output is a flat list of blocks with explicit type, labels, and attrs — useful when tooling needs the block structure without Terraform's schema conventions:

stategraph hcl json --safe < main.tf

[
  {
    "type": "resource",
    "labels": [ "aws_s3_bucket", "data" ],
    "attrs": [ { "bucket": "my-data" } ]
  }
]

stategraph hcl import

Import the HCL configuration files from the current directory into an existing state. Use this when the state already exists in Stategraph and you only need to (re)upload the configuration — for the combined state-plus-HCL onboarding, use stategraph import tf instead.

stategraph hcl import --tenant <tenant-id> --state <state-id> [options]

Options

Option Required Description
--tenant Yes Tenant ID (UUID), or set STATEGRAPH_TENANT_ID
--state Yes State ID (UUID) to import the HCL into
--workspace No Workspace for the state (default: "default")
-y No Auto-confirm interactive prompts
--silent No Suppress prompt output (only effective with -y)

Example

cd my-terraform-module
stategraph hcl import \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --state 7c9e6679-7425-40de-944b-e07fc1f90ae7

Debugging: stategraph test tf load

The stategraph test group holds debug helpers. test tf load parses a Terraform module directory the same way the importer does and prints the parsed HCL — local modules are inlined with a # module <address> comment. Use it to check how Stategraph reads your configuration when an import or plan does not pick up what you expect.

stategraph test tf load [--out <file>] <path>
Option Required Description
<path> Yes Path to a Terraform module directory
--out No Output file (defaults to stdout) 
stategraph test tf load .

Next Steps