Import Commands

The stategraph import command group onboards existing Terraform projects into Stategraph.

Commands

Command Description
stategraph import tf Create a state and import a Terraform state file plus its HCL in one step

import tf is the recommended onboarding command: it creates the state, uploads your terraform.tfstate, and imports the HCL configuration from the current directory in a single call. The lower-level pieces are also available separately — stategraph states import uploads only the state file, and stategraph hcl import imports only the HCL.

stategraph import tf

Create a new state and import both a Terraform state file and HCL configuration in one step. Run it from the root of your Terraform module so the HCL can be discovered.

stategraph import tf --tenant <tenant-id> --name <state-name> [options] <state-file>

Arguments

Argument Required Description
<state-file> Yes Path to the Terraform state file

Options

Option Required Description
--tenant Yes Tenant ID (UUID), or set STATEGRAPH_TENANT_ID
--name No* Name of the state to create
--workspace No Workspace for the state (default: "default")
--group No Group ID for the state
--overwrite No Overwrite an existing state (uses the state ID from stategraph.json)
--no-write-config No Do not write a stategraph.json config file
--var No Set a variable (key=value, repeatable)
--var-file No Path to a variable file
--attach-files No Attach files to resources matching an address glob, format ADDRESS_GLOB=FILE_GLOB (e.g., 'module.foo.*=**/*.yml'). Repeatable.
--force-files No Attach all files matching a path glob to every file() / templatefile() / fileset() call — an escape hatch for paths Stategraph cannot resolve statically. Repeatable.
--batch-size No Batch size for transaction log appends (performance tuning)
--parallel-batches No Number of parallel batches for transaction log appends (performance tuning)
-y No Auto-confirm interactive prompts
--silent No Suppress prompt output (only effective with -y)

*--name is required when creating a new state; with --overwrite the state is resolved from stategraph.json instead. If both --overwrite and --name are given, a new state is created when stategraph.json is absent.

Pass the same --var / --var-file flags you use with terraform plan so the HCL evaluates the way Terraform would evaluate it.

Example

Pull your current state and import it:

# From the root of your Terraform module
terraform state pull > terraform.tfstate

stategraph import tf \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --name "networking" \
  terraform.tfstate

After the import, a stategraph.json is written to the current directory binding it to the new state. Commit that file — later commands like stategraph tf plan use it to resolve the state.

Verify the import:

stategraph states summary --state <state-id>

Replacing an existing state

To replace a previously imported state with fresh HCL and state data, pass --overwrite:

stategraph import tf --overwrite \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --name "networking" \
  terraform.tfstate

Attaching external files

If your HCL reads external files via file(), templatefile(), or similar, tell Stategraph which files belong to which resources so they are included in change detection:

stategraph import tf \
  --tenant <tenant-id> \
  --name "app" \
  --attach-files 'module.app.*=templates/*.tpl' \
  terraform.tfstate

After import, the same mappings are managed with stategraph config files.

Next Steps