TrademarkTrademark
Features
Documentation
Pricing
About
Get Started
All articles

How to Use terraform chdir

Learn how Terraform’s -chdir flag lets you run plans from any folder, streamline multi-dir projects, and speed up CI without changing directories.
Sebastian StadilJune 18, 2025Updated March 31, 2026
How to Use terraform chdir
Key takeaways
  • The terraform -chdir=<PATH> global option, introduced in Terraform v0.14.0, makes Terraform switch to a specified directory before running a subcommand while the shell stays put.
  • With -chdir, path.root points to the target directory while path.cwd still points to where you ran the command, which differs from cd DIR && terraform.
  • Directory-based separation with -chdir gives each environment its own backend, provider versions, and state, offering stronger isolation than CLI workspaces.
  • In Terraform Cloud or Enterprise, a workspace's Working Directory setting is the equivalent of -chdir for VCS-driven runs.
  • As environments and teams grow, managing many separate -chdir contexts, variables, and policies adds operational overhead that platforms like Scalr centralize.

Fact checked by Ryan Fee on June 3, 2025.

Terraform defines and provisions infrastructure as code. As projects grow, you end up with multiple configurations: one for dev, staging, and prod, or one per microservice. Keeping them straight gets messy. And cd-ing into the right directory before every terraform apply is easy to get wrong, especially in an automated pipeline where a missed directory change runs the command in the wrong place. The -chdir flag is built for exactly this.

What Exactly is terraform -chdir?

Introduced back in Terraform v0.14.0, -chdir=<PATH> is a global option that tells Terraform to switch to a specific directory before running the command you give it (like init, plan, or apply). Your shell's current directory stays put, but Terraform operates as if it's in the directory you pointed it to.

The basic syntax is:

terraform -chdir=<PATH_TO_CONFIG_DIRECTORY> <SUBCOMMAND>

For example:

terraform -chdir=environments/production apply

This command would run terraform apply using the configuration files located in the environments/production subdirectory.

Why Bother With -chdir?

The point of -chdir is to make working with more than one Terraform setup less tedious.

  • Cleaner Multi-Config Management: Got separate folders for dev, staging, and prod? -chdir lets you target them without manually navigating.
  • Simpler Scripts: In your CI/CD pipelines or automation scripts, you don't need cd commands anymore. This makes your scripts cleaner and less likely to break if a cd fails or isn't undone properly.
  • Less Context Switching: You can fire off commands for different parts of your infrastructure from one spot in your terminal.
  • Fewer Errors: Less manual directory changing means fewer chances to run a command in the wrong place.

It's not quite the same as just doing cd DIR && terraform <command>. A key difference is how Terraform sees paths. With -chdir, path.cwd (current working directory for Terraform) still points to where you ran the command from, while path.root points to the directory you specified with -chdir. This can be useful for configurations that need to reference files outside their own directory but within the broader project.

Practical Ways to Use -chdir

Let's look at a few common scenarios.

1. Managing Multiple Environments

This is a big one. You probably have different setups for development, staging, and production. A common project structure might be:

my-project/
├── environments/
│   ├── dev/
│   │   └── main.tf
│   ├── staging/
│   │   └── main.tf
│   └── production/
│       └── main.tf
└── modules/
    └── ...

From the my-project/ root, you can manage each environment:

# Initialize development
terraform -chdir=environments/dev init
 
# Plan changes for production
terraform -chdir=environments/production plan
 
# Apply changes to staging
terraform -chdir=environments/staging apply

Each of these environment directories can have its own backend configuration, provider versions, and variable files, offering strong isolation. This is often preferred over CLI workspaces when backend configurations or even provider versions need to differ significantly between environments.

2. Component-Based Infrastructure

If your system is broken into smaller pieces (VPC, DNS, app services, databases), -chdir helps manage them independently.

my-infra/
├── vpc/
│   └── main.tf
├── dns/
│   └── main.tf
├── app-service-a/
│   └── main.tf
└── database-main/
    └── main.tf

You can then target specific components:

terraform -chdir=my-infra/vpc apply
terraform -chdir=my-infra/app-service-a plan

This modularity is great for larger teams or when you want to limit the blast radius of changes.

3. CI/CD Pipelines

In a pipeline, -chdir keeps each step's target directory explicit.

# Example CI/CD pipeline steps
jobs:
  deploy-dev:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
 
      - name: Init Dev VPC
        run: terraform -chdir=environments/dev/vpc init
 
      - name: Apply Dev VPC
        run: terraform -chdir=environments/dev/vpc apply -auto-approve
 
  deploy-prod-app:
    runs-on: ubuntu-latest
    needs: deploy-dev # Example dependency
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
 
      - name: Init Prod App
        run: terraform -chdir=environments/prod/app init
 
      - name: Plan Prod App
        run: terraform -chdir=environments/prod/app plan

No more cd some/path && terraform apply && cd ../.. gymnastics. Each step is explicit about its target. However, as the number of these -chdir targets grows, managing the orchestration, variable injection, and ensuring consistent execution across all of them in a CI/CD system can introduce its own layer of complexity.

-chdir vs. CLI Workspaces

Terraform CLI workspaces also let you manage multiple states from a single configuration. So which one fits your case?

  • CLI Workspaces: Good for when you have minor variations of the same infrastructure and they can all share the same backend configuration. Think feature branches or temporary testing environments.
  • Directory-Based Separation (with -chdir): Better when environments need different backend configurations, different provider versions, or have significantly different infrastructure. This provides stronger isolation.

Here’s a quick comparison:

Feature Directory-Based with -chdir CLI Workspaces
Backend Configuration Can be entirely separate per directory (different types, accounts, credentials). Shared by all workspaces within the same working directory configuration.
State File Location Each directory has its own terraform.tfstate (or remote equivalent) and .terraform dir. Separate state files per workspace (e.g., terraform.tfstate.d/<workspace_name>/terraform.tfstate for local backend) within one config dir.
Provider Configuration Can be separate per directory (different versions, aliases). Shared by all workspaces.
Code Duplication Higher risk if not using modules effectively; configurations are physically separate. Lower; uses the same set of .tf files, with variations via terraform.workspace or input variables.
Isolation Level Stronger; physical separation of configuration, state, and backend. Weaker; all workspaces share the same backend configuration and often the same credentials.
Ideal Use Cases Managing distinct environments (dev, prod) with different backends/credentials, complex components. Managing minor variations of the same infrastructure (e.g., feature branches, parallel test environments) with a shared backend.

The -chdir approach gives you better isolation for distinct backends. The cost is that you now have many separate configurations to track, each with its own state and variables, and that tracking gets harder as the team grows.

-chdir and Backend/Provider/Module Management

  • Backend Config: Terraform looks for backend configuration files (backend.tf) inside the -chdir directory. The .terraform directory (with plugin caches and backend info) is also created and managed there. This is key for isolation.
  • Provider/Module Caching: By default, each -chdir target directory gets its own cache of provider plugins and modules in its .terraform subdirectory. This can mean downloading the same provider multiple times. To avoid this, you can set up a global plugin_cache_dir in your Terraform CLI configuration file (terraform.rc or terraform.cfg). This is a good idea for performance, especially in CI.
  • Module source Paths: Relative module source paths (e.g., source = "../../shared_modules/network") are resolved relative to the configuration file within the -chdir target directory.

What About Terraform Cloud/Enterprise?

If you're using Terraform Cloud or Enterprise, the "Working Directory" setting in a workspace is basically the -chdir equivalent. TFC/TFE will "change to" that directory in your VCS repo before running Terraform commands. This is great because it means you can often keep your multi-directory project structure when moving to a managed Terraform service.

Tips and Potential Snags

  • Keep Structure Consistent: Use a clear, predictable directory layout (e.g., environments/<env_name>/, components/<component_name>/).
  • Automate It: -chdir is really built for scripts and CI/CD.
  • Know Your Paths: Remember path.root is the -chdir target, and path.cwd is where you ran the command.
  • Always init: Run terraform -chdir=DIR init for each target directory first.
  • Use plugin_cache_dir: It'll speed things up.

A known issue can pop up with terraform init -chdir if you're using implicit filesystem mirrors for providers (like a terraform.d/plugins/ in your current directory). Terraform might get confused about where to find them. The workaround is often to move that mirror relative to the -chdir target, or better yet, rely on the official provider registry or explicit provider_installation blocks.

Beyond -chdir: Scaling Challenges

The -chdir option beats navigating directories by hand. It brings clarity to local workflows and CI/CD scripts. But the work of managing those separate execution contexts doesn't go away as the number of environments, components, and teams grows. It moves around.

Once you're relying on -chdir plus custom scripting, a few things get hard at the same time: keeping execution consistent, handling variables and secrets safely across dozens of configurations, enforcing policies like tagging or security group rules, and seeing all of your infrastructure in one place. This is usually the point where teams start looking for a platform instead. Scalr builds on these same concepts as a centralized control plane for Terraform operations. It offers hierarchical variable management, role-based access control (RBAC) scoped to environments or components, automated policy enforcement (via OPA, for example), and cost estimation before changes are applied. Those are hard to build and maintain yourself on top of raw -chdir workflows.

Wrapping Up

terraform -chdir helps organize complex projects and makes automation cleaner. Once you know how it behaves with backends, workspaces, and modules, you can put it to work without surprises.

For a lot of teams, -chdir gives them the control and organization they need. But as an IaC practice scales, managing a pile of separate configurations gets complicated, and that's often when people start looking at platforms like Scalr for more abstraction, governance, and collaboration across the whole setup.

About the Author

Sebastian Stadil, CEO and founder of Scalr, brings over 15 years of DevOps experience. His experience dates back to using AWS in 2004, even before the S3 public beta. He is also the program chair for OpenTofu at the Linux Foundation and previously advised Microsoft Azure and Google Cloud, serving a combined ten years on their respective Cloud Advisory Boards.

Sources

About the author
Sebastian StadilCEO at Scalr
Sebastian Stadil is the CEO of Scalr with 15+ years of DevOps experience. He started with AWS in 2004 and advised early Microsoft Azure and Google Cloud.
Part of
Thumbnail of The Developer's Guide to HCL

The Developer's Guide to HCL

What is HCL? Learn the basics of HashiCorp Configuration Language, its purpose, design goals, and how it compares to JSON and YAML for Infrastructure as Code.
Sebastian Stadil
March 9, 2026
More on this topic
Terraform moved blocks: refactoring without pain
Terraform Outputs: How to with Examples
Understanding the Terraform ignore_changes Lifecycle Block
A Concise Guide to terraform_data Resource
Advanced Terraform Workflows with terraform_data
Terraform Resource Dependencies Explained
The Three Stages of Terraform's Lifecycle Meta Argument