opentf/website/docs/cli/commands/plan.mdx

---
page_title: 'Command: plan'
description: >-
  The opentf plan command creates an execution plan with a preview of the
  changes that OpenTF will make to your infrastructure.
---

# Command: plan

The `opentf plan` command creates an execution plan, which lets you preview
the changes that OpenTF plans to make to your infrastructure. By default,
when OpenTF creates a plan it:

* Reads the current state of any already-existing remote objects to make sure
  that the OpenTF state is up-to-date.
* Compares the current configuration to the prior state and noting any
  differences.
* Proposes a set of change actions that should, if applied, make the remote
  objects match the configuration.

The `plan` command alone does not actually carry out the proposed changes You can use this command to check whether the proposed changes match what
you expected before you apply the changes or share your changes with your
team for broader review.

If OpenTF detects that no changes are needed to resource instances or to
root module output values, `opentf plan` will report that no actions need
to be taken.

If you are using OpenTF directly in an interactive terminal and you expect
to apply the changes OpenTF proposes, you can alternatively run
[`opentf apply`](/opentf/cli/commands/apply) directly. By default, the "apply" command
automatically generates a new plan and prompts for you to approve it.

You can use the optional `-out=FILE` option to save the generated plan to a
file on disk, which you can later execute by passing the file to
[`opentf apply`](/opentf/cli/commands/apply) as an extra argument. This two-step workflow
is primarily intended for when running OpenTF in automation.

If you run `opentf plan` without the `-out=FILE` option then it will create
a _speculative plan_, which is a description of the effect of the plan but
without any intent to actually apply it.

In teams that use a version control and code review workflow for making changes
to real infrastructure, developers can use speculative plans to verify the
effect of their changes before submitting them for code review. However, it's
important to consider that other changes made to the target system in the
meantime might cause the final effect of a configuration change to be different
than what an earlier speculative plan indicated, so you should always re-check
the final non-speculative plan before applying to make sure that it still
matches your intent.

## Usage

Usage: `opentf plan [options]`

The `plan` subcommand looks in the current working directory for the root module
configuration.

Because the plan command is one of the main commands of OpenTF, it has
a variety of different options, described in the following sections. However,
most of the time you should not need to set any of these options, because
a OpenTF configuration should typically be designed to work with no special
additional options for routine work.

The remaining sections on this page describe the various options:

* **[Planning Modes](#planning-modes)**: There are some special alternative
  planning modes that you can use for some special situations where your goal
  is not just to change the remote system to match your configuration.
* **[Planning Options](#planning-options)**: Alongside the special planning
  modes, there are also some options you can set in order to customize the
  planning process for unusual needs.
  * **[Resource Targeting](#resource-targeting)** is one particular
    special planning option that has some important caveats associated
    with it.
* **[Other Options](#other-options)**: These change the behavior of the planning
  command itself, rather than customizing the content of the generated plan.

## Planning Modes

The previous section describes OpenTF's default planning behavior, which
changes the remote system to match the changes you make to
your configuration. OpenTF has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for  both `opentf plan` and [`opentf apply`](/opentf/cli/commands/apply).

* **Destroy mode:** creates a plan whose goal is to destroy all remote objects
  that currently exist, leaving an empty OpenTF state. It is the same as running [`opentf destroy`](/opentf/cli/commands/destroy). Destroy mode can be useful for situations like transient development environments, where the managed objects cease to be useful once the development task is complete.

  Activate destroy mode using the `-destroy` command line option.

* **Refresh-only mode:** creates a plan whose goal is only to update the
  OpenTF state and any root module output values to match changes made to
  remote objects outside of OpenTF. This can be useful if you've
  intentionally changed one or more remote objects outside of the usual
  workflow (e.g. while responding to an incident) and you now need to reconcile
  OpenTF's records with those changes.

  Activate refresh-only mode using the `-refresh-only` command line option.

In situations where we need to discuss the default planning mode that OpenTF
uses when none of the alternative modes are selected, we refer to it as
"Normal mode". Because these alternative modes are for specialized situations
only, some other OpenTF documentation only discusses the normal planning
mode.

The planning modes are all mutually-exclusive, so activating any non-default
planning mode disables the "normal" planning mode, and you can't use more than
one alternative mode at the same time.

## Planning Options

In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for  both `opentf plan` and [`opentf apply`](/opentf/cli/commands/apply).

- `-refresh=false` - Disables the default behavior of synchronizing the
  OpenTF state with remote objects before checking for configuration changes. This can make the planning operation faster by reducing the number of remote API requests. However, setting `refresh=false` causes OpenTF to ignore external changes, which could result in an incomplete or incorrect plan. You cannot use `refresh=false` in refresh-only planning mode because it would effectively disable the entirety of the planning operation.

- `-replace=ADDRESS` - Instructs OpenTF to plan to replace the
  resource instance with the given address. This is helpful when one or more remote objects have become degraded, and you can use replacement objects with the same configuration to align with immutable infrastructure patterns. OpenTF will use a "replace" action if the specified resource would normally cause an "update" action or no action at all. Include this option multiple times to replace several objects at once. You cannot use `-replace` with the `-destroy` option.

- `-target=ADDRESS` - Instructs OpenTF to focus its planning efforts only
  on resource instances which match the given address and on any objects that
  those instances depend on.

  -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around OpenTF limitations. Refer to [Resource Targeting](#resource-targeting) for more details.

- `-var 'NAME=VALUE'` - Sets a value for a single
  [input variable](/opentf/language/values/variables) declared in the
  root module of the configuration. Use this option multiple times to set
  more than one variable. Refer to
  [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information.

- `-var-file=FILENAME` - Sets values for potentially many
  [input variables](/opentf/language/values/variables) declared in the
  root module of the configuration, using definitions from a
  ["tfvars" file](/opentf/language/values/variables#variable-definitions-tfvars-files).
  Use this option multiple times to include values from more than one file.

There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](/opentf/language/values/variables#assigning-values-to-root-module-variables) for more information.

### Input Variables on the Command Line

You can use the `-var` command line option to specify values for
[input variables](/opentf/language/values/variables) declared in your
root module.

However, to do so will require writing a command line that is parsable both
by your chosen command line shell _and_ OpenTF, which can be complicated
for expressions involving lots of quotes and escape sequences. In most cases
we recommend using the `-var-file` option instead, and write your actual values
in a separate file so that OpenTF can parse them directly, rather than
interpreting the result of your shell's parsing.

~> **Warning:** OpenTF will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`).

To use `-var` on a Unix-style shell on a system like Linux or macOS we
recommend writing the option argument in single quotes `'` to ensure the
shell will interpret the value literally:

```
opentf plan -var 'name=value'
```

If your intended value also includes a single quote then you'll still need to
escape that for correct interpretation by your shell, which also requires
temporarily ending the quoted sequence so that the backslash escape character
will be significant:

```
opentf plan -var 'name=va'\''lue'
```

When using OpenTF on Windows, we recommend using the Windows Command Prompt
(`cmd.exe`). When you pass a variable value to OpenTF from the Windows
Command Prompt, use double quotes `"` around the argument:

```
opentf plan -var "name=value"
```

If your intended value includes literal double quotes then you'll need to
escape those with a backslash:

```
opentf plan -var "name=va\"lue"
```

PowerShell on Windows cannot correctly pass literal quotes to external programs,
so we do not recommend using OpenTF with PowerShell when you are on Windows.
Use Windows Command Prompt instead.

The appropriate syntax for writing the variable value is different depending
on the variable's [type constraint](/opentf/language/expressions/type-constraints).
The primitive types `string`, `number`, and `bool` all expect a direct string
value with no special punctuation except that required by your shell, as
shown in the above examples. For all other type constraints, including list,
map, and set types and the special `any` keyword, you must write a valid
OpenTF language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell
literally to OpenTF. For example, for a `list(string)` type constraint:

```
# Unix-style shell
opentf plan -var 'name=["a", "b", "c"]'

# Windows Command Prompt (do not use PowerShell on Windows)
opentf plan -var "name=[\"a\", \"b\", \"c\"]"
```

Similar constraints apply when setting input variables using environment
variables. For more information on the various methods for setting root module
input variables, see
[Assigning Values to Root Module Variables](/opentf/language/values/variables#assigning-values-to-root-module-variables).

### Resource Targeting

You can use the `-target` option to focus OpenTF's attention on only a
subset of resources.
You can use [resource address syntax](/opentf/cli/state/resource-addressing)
to specify the constraint. OpenTF interprets the resource address as follows:

* If the given address identifies one specific resource instance, OpenTF
  will select that instance alone. For resources with either `count` or
  `for_each` set, a resource instance address must include the instance index
  part, like `aws_instance.example[0]`.

* If the given address identifies a resource as a whole, OpenTF will select
  all of the instances of that resource. For resources with either `count`
  or `for_each` set, this means selecting _all_ instance indexes currently
  associated with that resource. For single-instance resources (without
  either `count` or `for_each`), the resource address and the resource instance
  address are identical, so this possibility does not apply.

* If the given address identifies an entire module instance, OpenTF will
  select all instances of all resources that belong to that module instance
  and all of its child module instances.

Once OpenTF has selected one or more resource instances that you've directly
targeted, it will also then extend the selection to include all other objects
that those selections depend on either directly or indirectly.

This targeting capability is provided for exceptional circumstances, such
as recovering from mistakes or working around OpenTF limitations. It
is _not recommended_ to use `-target` for routine operations, since this can
lead to undetected configuration drift and confusion about how the true state
of resources relates to configuration.

Instead of using `-target` as a means to operate on isolated portions of very
large configurations, prefer instead to break large configurations into
several smaller configurations that can each be independently applied.
[Data sources](/opentf/language/data-sources) can be used to access
information about resources created in other configurations, allowing
a complex system architecture to be broken down into more manageable parts
that can be updated independently.

## Other Options

The `opentf plan` command also has some other options that are related to
the input and output of the planning command, rather than customizing what
sort of plan OpenTF will create. These commands are not necessarily also
available on `opentf apply`, unless otherwise stated in the documentation
for that command.

The available options are:

* `-compact-warnings` - Shows any warning messages in a compact form which
  includes only the summary messages, unless the warnings are accompanied by
  at least one error and thus the warning text might be useful context for
  the errors.

* `-detailed-exitcode` - Returns a detailed exit code when the command exits.
  When provided, this argument changes the exit codes and their meanings to
  provide more granular information about what the resulting plan contains:
  * 0 = Succeeded with empty diff (no changes)
  * 1 = Error
  * 2 = Succeeded with non-empty diff (changes present)

- `-generate-config-out=PATH` - (Experimental) If `import` blocks are present in configuration, instructs OpenTF to generate HCL for any imported resources not already present. The configuration is written to a new file at PATH, which must not already exist, or OpenTF will error. If the plan fails for another reason, OpenTF may still attempt to write configuration.

* `-input=false` - Disables OpenTF's default behavior of prompting for
  input for root module input variables that have not otherwise been assigned
  a value. This option is particularly useful when running OpenTF in
  non-interactive automation systems.

* `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output.
  This implies `-input=false`, so the configuration must have no unassigned
  variable values to continue.

  [machine-readable-ui]: /opentf/internals/machine-readable-ui

* `-lock=false` - Don't hold a state lock during the operation. This is
  dangerous if others might concurrently run commands against the same
  workspace.

* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
  instructs OpenTF to retry acquiring a lock for a period of time before
  returning an error. The duration syntax is a number followed by a time
  unit letter, such as "3s" for three seconds.

* `-no-color` - Disables terminal formatting sequences in the output. Use this
  if you are running OpenTF in a context where its output will be
  rendered by a system that cannot interpret terminal formatting.

* `-out=FILENAME` - Writes the generated plan to the given filename in an
  opaque file format that you can later pass to `opentf apply` to execute
  the planned changes, and to some other OpenTF commands that can work with
  saved plan files.

  OpenTF will allow any filename for the plan file, but a typical
  convention is to name it `tfplan`. **Do not** name the file with a suffix
  that OpenTF recognizes as another file format; if you use a `.tf` suffix
  then OpenTF will try to interpret the file as a configuration source
  file, which will then cause syntax errors for subsequent commands.

  The generated file is not in any standard format intended for consumption
  by other software, but the file _does_ contain your full configuration,
  all of the values associated with planned changes, and all of the plan
  options including the input variables. If your plan includes any sort of
  sensitive data, even if obscured in OpenTF's terminal output, it will
  be saved in cleartext in the plan file. You should therefore treat any
  saved plan files as potentially-sensitive artifacts.

* `-parallelism=n` - Limit the number of concurrent operations as OpenTF
  [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults
  to 10.

For configurations using
[the `local` backend](/opentf/language/settings/backends/local) only,
`opentf plan` accepts the legacy command line option
[`-state`](/opentf/language/settings/backends/local#command-line-arguments).

### Passing a Different Configuration Directory

If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes OpenTF consistently look
in the given directory for all files it would normally read or write in the
current working directory.