IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update website/docs/cli. (#171)

Browse Source 
* Initial renaming, rewriting and cleaning up wave for the CLI docs.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

* More renaming.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

* More renaming.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

* More renaming.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

* Remove tutorial references.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

* Post-review fixes.

Signed-off-by: Jakub Martin <kubam@spacelift.io>

---------

Signed-off-by: Jakub Martin <kubam@spacelift.io>
This commit is contained in:
Kuba Martin 2023-08-25 11:09:18 +02:00 committed by GitHub
parent 697267ae11
commit 4d665a0091
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
70 changed files with 1090 additions and 1560 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
website/docs/cli/auth/index.mdx
View File

@ -1,31 +1,26 @@
--- ---
page_title: Authentication - Terraform CLI page_title: Authentication - OpenTF CLI
description: >- description: >-
Documentation about the login and logout commands that help automate getting Documentation about the login and logout commands that help automate getting
an API token for your Terraform Cloud account. an API token for your cloud backend account.
--- ---
# CLI Authentication # CLI Authentication
> **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](/terraform/tutorials/cloud/cloud-login?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. TACOS (TF Automation and Collaboration Software) are platforms that perform as part of their
offering OpenTF runs to provision infrastructure, offering a collaboration-focused
environment that makes it easier for teams to use OpenTF together.
[Terraform Cloud](https://cloud.hashicorp.com/products/terraform) and OpenTF CLI integrates with TACOS in several ways — it can be a
[Terraform Enterprise](/terraform/enterprise) are platforms that perform front-end for CLI-driven runs, and can also use some TACOS as a state backend, a private module
Terraform runs to provision infrastructure, offering a collaboration-focused registry, or a private provider registry. All of these integrations require you to authenticate OpenTF CLI
environment that makes it easier for teams to use Terraform together. (For with your TACOS account.
expediency, the content below refers to both products as "Terraform Cloud.")
Terraform CLI integrates with Terraform Cloud in several ways — it can be a
front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in Terraform Cloud,
and can also use Terraform Cloud as a state backend and a private module
registry. All of these integrations require you to authenticate Terraform CLI
with your Terraform Cloud account.
The best way to handle CLI authentication is with the `login` and `logout` The best way to handle CLI authentication is with the `login` and `logout`
commands, which help automate the process of getting an API token for your commands, which help automate the process of getting an API token for your
Terraform Cloud user account. TACOS user account.
For details, see: For details, see:
- [The `terraform login` command](/terraform/cli/commands/login) - [The `opentf login` command](/opentf/cli/commands/login)
- [The `terraform logout` command](/terraform/cli/commands/logout) - [The `opentf logout` command](/opentf/cli/commands/logout)

10
website/docs/cli/cloud/command-line-arguments.mdx
View File

@ -6,19 +6,19 @@ description: Command Line Arguments
# Command Line Arguments # Command Line Arguments
When your configuration includes a `cloud` block, commands that When your configuration includes a `cloud` block, commands that
make local modifications to Terraform state and then push them back up to the remote workspace make local modifications to OpenTF state and then push them back up to the remote workspace
accept the following option to modify that behavior: accept the following option to modify that behavior:
- `-ignore-remote-version` - Override checking that the local and remote - `-ignore-remote-version` - Override checking that the local and remote
Terraform versions agree, making an operation proceed even when there is OpenTF versions agree, making an operation proceed even when there is
a mismatch. a mismatch.
State-modification operations usually require using a local version of the State-modification operations usually require using a local version of the
Terraform CLI that is compatible with the Terraform version selected OpenTF CLI that is compatible with the OpenTF version selected
in the remote workspace settings. This prevents the in the remote workspace settings. This prevents the
local operation from creating a new state snapshot that the workspace's local operation from creating a new state snapshot that the workspace's
remote execution environment cannot decode. remote execution environment cannot decode.
We recommend against using this option unless absolutely necessary. Overriding this check can result We recommend against using this option unless absolutely necessary. Overriding this check can result
in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently in a cloud backend workspace that is no longer able to complete remote operations with the currently
selected version of Terraform. selected version of OpenTF.

27
website/docs/cli/cloud/index.mdx
View File

@ -1,27 +1,20 @@
--- ---
page_title: Using Terraform Cloud - Terraform CLI page_title: Using the Cloud Backend - OpenTF CLI
description: >- description: >-
Learn how to use Terraform Cloud and Terraform Enterprise on the command line with the Terraform CLI. Learn how to use a cloud backend on the command line with the OpenTF CLI.
--- ---
# Using Terraform Cloud with Terraform CLI # Using the Cloud Backend with OpenTF CLI
The Terraform CLI integration with Terraform Cloud lets you use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated. The OpenTF CLI lets you use cloud backends on the command line.
Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/terraform/cloud-docs/run/cli). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking. When you use the cloud backend CLI workflow, operations like `opentf plan` or `opentf apply` are remotely executed in the cloud backend's run environment by default, with log output streaming to the local terminal. This lets you use cloud backend's features within the familiar OpenTF CLI workflow. Cloud backend services may choose to implement only a subset of the available features.
> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial. Workspaces can also be configured for local execution, in which case the cloud backend only stores state. In this mode, the cloud backend behaves just like a standard state backend.
Workspaces can also be configured for local execution, in which case Terraform Cloud only stores state. In this mode, Terraform Cloud behaves just like a standard state backend.
-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote). Refer to [Migrating from the remote
backend](/terraform/cli/cloud/migrating) for details about switching to the CLI integration.
## Documentation Summary ## Documentation Summary
- [Terraform Cloud Settings](/terraform/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support. - [Cloud Backend Settings](/opentf/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable cloud backend support.
- [Initializing and Migrating](/terraform/cli/cloud/migrating) describes - [Initializing and Migrating](/opentf/cli/cloud/migrating) describes
how to start using Terraform Cloud with a working directory that already has state data. how to start using the cloud backend with a working directory that already has state data.
- [Command Line Arguments](/terraform/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud. - [Command Line Arguments](/opentf/cli/cloud/command-line-arguments) lists the OpenTF command flags that are specific to using OpenTF with the cloud backend.
Refer to the [CLI-driven Run Workflow](/terraform/cloud-docs/run/cli) for more details about how to use Terraform Cloud from the command line.

43
website/docs/cli/cloud/migrating.mdx
View File

@ -1,50 +1,47 @@
--- ---
page_title: Initializing and Migrating to Terraform Cloud - Terraform CLI page_title: Initializing and Migrating to a Cloud Backend - OpenTF CLI
description: >- description: >-
Learn how to use the Terraform CLI to migrate local or remote state to Terraform Cloud. Learn how to use the OpenTF CLI to migrate local or remote state to a Cloud Backend.
--- ---
# Initializing and Migrating # Initializing and Migrating
After [configuring Terraform Cloud settings](/terraform/cli/cloud/settings) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for more details. After [configuring cloud backend settings](/opentf/cli/cloud/settings) for a working directory, you must run `opentf init` to finish setting up. If the working directory has no existing OpenTF state, you can start using OpenTF with a cloud backend right away.
When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces. When you run `opentf init` in the following scenarios, OpenTF will ask you to choose whether or not to migrate state from any existing workspaces.
1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces. 1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, OpenTF will ask if you would like to migrate that state to new cloud backend workspaces.
1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block. 1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to a cloud backend with the `remote` backend, OpenTF can continue using the same cloud backend workspaces. You will need to switch the `remote` backend block to the `cloud` block.
## Migrating from Local State or State Backends ## Migrating from Local State or State Backends
> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial.
If the working directory already has state data available (using either local state or a [state If the working directory already has state data available (using either local state or a [state
backend](/terraform/language/settings/backends/configuration)), Terraform asks your approval to migrate backend](/opentf/language/settings/backends/configuration)), OpenTF asks your approval to migrate
that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles that state to the cloud backend. You will need permission to manage workspaces in the destination cloud backend organization. This process is interactive and self-documenting, and resembles
moving between state backends. moving between state backends.
Terraform may also prompt you to rename your workspaces during the migration, to either give a name to OpenTF may also prompt you to rename your workspaces during the migration, to either give a name to
the unnamed `default` workspace (Terraform Cloud requires all workspaces to have a name) or give the unnamed `default` workspace (the cloud backend requires all workspaces to have a name) or give
your workspace names more contextual information. Unlike Terraform CLI-only workspaces, which represent your workspace names more contextual information. Unlike OpenTF CLI-only workspaces, which represent
multiple environments associated with the same configuration (e.g. production, staging, development), multiple environments associated with the same configuration (e.g. production, staging, development),
Terraform Cloud workspaces can represent totally independent configurations, and must have unique names within the Terraform Cloud organization. cloud backend workspaces can represent totally independent configurations, and must have unique names within the cloud backend organization.
Because of this, Terraform will prompt you to rename the working directory's workspaces Because of this, OpenTF will prompt you to rename the working directory's workspaces
according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`, `<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
`networking-staging-us-east`). Refer to [Workspace `networking-staging-us-east`).
Naming](/terraform/cloud-docs/workspaces/naming) in the Terraform Cloud documentation for more detail.
## Migrating from the `remote` Backend ## Migrating from the `remote` Backend
If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names. If the working directory was already connected to a cloud backend with the `remote` backend, OpenTF can continue using the same cloud backend workspaces. The local names shown for those workspaces will change to match their remote names.
The [`remote` backend](/terraform/language/settings/backends/remote) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. The [`remote` backend](/opentf/language/settings/backends/remote) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTF and Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
### Block Replacement ### Block Replacement
When switching from the `remote` backend to a `cloud` block, Terraform will continue using the same When switching from the `remote` backend to a `cloud` block, OpenTF will continue using the same
set of Terraform Cloud workspaces. Replace your `backend "remote"` block with an equivalent `cloud` set of cloud backend workspaces. Replace your `backend "remote"` block with an equivalent `cloud`
block. block.
#### Single Workspace #### Single Workspace
@ -69,7 +66,7 @@ terraform {
If you were using multiple workspaces with the `prefix` argument, replace it with a `cloud` block that uses the `tags` argument. You may specify any number of tags to distinguish the workspaces for your working directory, but a good starting point may be to use whatever the prefix was before. If you were using multiple workspaces with the `prefix` argument, replace it with a `cloud` block that uses the `tags` argument. You may specify any number of tags to distinguish the workspaces for your working directory, but a good starting point may be to use whatever the prefix was before.
The tags you configure do not need to be present on the existing workspaces. When you initialize, Terraform will add the specified tags to the workspaces if necessary. The tags you configure do not need to be present on the existing workspaces. When you initialize, OpenTF will add the specified tags to the workspaces if necessary.
```diff ```diff
terraform { terraform {
@ -85,4 +82,4 @@ terraform {
} }
``` ```
~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the Terraform CLI. For example, rather than `terraform workspace select prod`, you must run the command `terraform workspace select my-app-prod`. ~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the OpenTF CLI. For example, rather than `opentf workspace select prod`, you must run the command `opentf workspace select my-app-prod`.

74
website/docs/cli/cloud/settings.mdx
View File

@ -1,38 +1,35 @@
--- ---
page_title: Terraform Cloud Settings - Terraform CLI page_title: Cloud Backend Settings - OpenTF CLI
description: >- description: >-
Configure the Terraform Cloud CLI integration. Configure the Cloud Backend CLI integration.
--- ---
# Terraform Cloud Settings # Cloud Backend Settings
Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's OpenTF CLI can integrate with a cloud backend, acting as a client for it.
[CLI-driven run workflow](/terraform/cloud-docs/run/cli).
> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial. You must configure the following settings to use the cloud backend for a particular working directory:
You must configure the following settings to use Terraform Cloud for a particular working directory: - Provide credentials to access the cloud backend, preferably by using the
[`opentf login`](/opentf/cli/commands/login) command.
- Provide credentials to access Terraform Cloud, preferably by using the - Add a `cloud` block to the directory's OpenTF configuration, to specify
[`terraform login`](/terraform/cli/commands/login) command.
- Add a `cloud` block to the directory's Terraform configuration, to specify
which organization and workspace(s) to use. which organization and workspace(s) to use.
- Optionally, use a `.terraformignore` file to specify files that shouldn't be - Optionally, use a `.terraformignore` file to specify files that shouldn't be
uploaded with the Terraform configuration when running plans and applies. uploaded with the OpenTF configuration when running plans and applies.
After adding or changing a `cloud` block, you must run `terraform init`. After adding or changing a `cloud` block, you must run `opentf init`.
## The `cloud` Block ## The `cloud` Block
The `cloud` block is a nested block within the top-level `terraform` settings The `cloud` block is a nested block within the top-level `terraform` settings
block. It specifies which Terraform Cloud workspaces to use for the current block. It specifies which cloud backend workspaces to use for the current
working directory. working directory.
```hcl ```hcl
terraform { terraform {
cloud { cloud {
organization = "my-org" organization = "my-org"
hostname = "app.terraform.io" # Optional; defaults to app.terraform.io hostname = "app.example.org" # Optional; defaults to app.terraform.io
workspaces { workspaces {
project = "networking-development" project = "networking-development"
@ -45,12 +42,12 @@ terraform {
The `cloud` block also has some special restrictions: The `cloud` block also has some special restrictions:
- A configuration can only provide one `cloud` block. - A configuration can only provide one `cloud` block.
- A `cloud` block cannot be used with [state backends](/terraform/language/settings/backends/configuration). - A `cloud` block cannot be used with [state backends](/opentf/language/settings/backends/configuration).
A configuration can use one or the other, but not both. A configuration can use one or the other, but not both.
- A `cloud` block cannot refer to named values (like input variables, locals, or - A `cloud` block cannot refer to named values (like input variables, locals, or
data source attributes). data source attributes).
The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration The `cloud` block only affects OpenTF CLI's behavior. When the cloud backend uses a configuration
that contains a cloud block - for example, when a workspace is configured to use a VCS provider that contains a cloud block - for example, when a workspace is configured to use a VCS provider
directly - it ignores the block and behaves according to its own workspace settings. directly - it ignores the block and behaves according to its own workspace settings.
@ -61,56 +58,53 @@ The `cloud` block supports the following configuration arguments:
- `organization` - (Required) The name of the organization containing the - `organization` - (Required) The name of the organization containing the
workspace(s) the current configuration should use. workspace(s) the current configuration should use.
- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to - `workspaces` - (Required) A nested block that specifies which remote cloud backend workspaces to
use for the current configuration. The `workspaces` block must contain **exactly one** of the use for the current configuration. The `workspaces` block must contain **exactly one** of the
following arguments, each denoting a strategy for how workspaces should be mapped: following arguments, each denoting a strategy for how workspaces should be mapped:
- `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use - `tags` - (Optional) A set of cloud backend workspace tags. You will be able to use
this working directory with any workspaces that have all of the specified tags, this working directory with any workspaces that have all of the specified tags,
and can use [the `terraform workspace` commands](/terraform/cli/workspaces) and can use [the `opentf workspace` commands](/opentf/cli/workspaces)
to switch between them or create new workspaces. New workspaces will automatically have to switch between them or create new workspaces. New workspaces will automatically have
the specified tags. This option conflicts with `name`. the specified tags. This option conflicts with `name`.
- `name` - (Optional) The name of a single Terraform Cloud workspace. You will - `name` - (Optional) The name of a single cloud backend workspace. You will
only be able to use the workspace specified in the configuration with this working only be able to use the workspace specified in the configuration with this working
directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or directory, and cannot manage workspaces from the CLI (e.g. `opentf workspace select` or
`terraform workspace new`). This option conflicts with `tags`. `opentf workspace new`). This option conflicts with `tags`.
- `project` - (Optional) The name of a Terraform Cloud project. Workspaces that need created will - `project` - (Optional) The name of a cloud backend project. Workspaces that need created will
will be created within this project. `terraform workspace list` will be filtered by workspaces will be created within this project. `opentf workspace list` will be filtered by workspaces
in the supplied project. in the supplied project.
- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform - `hostname` - (Optional) The hostname of the cloud backend.
Enterprise. Defaults to Terraform Cloud (app.terraform.io).
- `token` - (Optional) The token used to authenticate with Terraform Cloud. - `token` - (Optional) The token used to authenticate with the cloud backend.
We recommend omitting the token from the configuration, and instead using We recommend omitting the token from the configuration, and instead using
[`terraform login`](/terraform/cli/commands/login) or manually configuring [`opentf login`](/opentf/cli/commands/login) or manually configuring
`credentials` in the `credentials` in the
[CLI config file](/terraform/cli/config/config-file#credentials). [CLI config file](/opentf/cli/config/config-file#credentials).
### Environment Variables ### Environment Variables
-> **Note:** CLI integration environment variables are supported in Terraform v1.2.0 and later. You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure OpenTF as part of a Continuous Integration (CI) pipeline. OpenTF only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file.
You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file. ~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline.
~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to [Non-Interactive Workflows](/terraform/cloud-docs/run/cli#non-interactive-workflows) for details.
Use the following environment variables to configure the `cloud` block: Use the following environment variables to configure the `cloud` block:
- `TF_CLOUD_ORGANIZATION` - The name of the organization. Terraform reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence. - `TF_CLOUD_ORGANIZATION` - The name of the organization. OpenTF reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence.
- `TF_CLOUD_HOSTNAME` - The hostname of a Terraform Enterprise installation. Terraform reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence. - `TF_CLOUD_HOSTNAME` - The hostname of the cloud backend. OpenTF reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence.
- `TF_CLOUD_PROJECT` - The name of a Terraform Cloud project. Terraform reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence. - `TF_CLOUD_PROJECT` - The name of a cloud backend project. OpenTF reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence.
- `TF_WORKSPACE` - The name of a single Terraform Cloud workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. Terraform Cloud will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/terraform/cli/config/environment-variables#tf_workspace) for details. - `TF_WORKSPACE` - The name of a single cloud backend workspace. OpenTF reads this when `workspaces` is omitted from the `cloud` block. The cloud backend will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/opentf/cli/config/environment-variables#tf_workspace) for details.
## Excluding Files from Upload with .terraformignore ## Excluding Files from Upload with .terraformignore
When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli), When executing a remote `plan` or `apply` in a CLI-driven run,
a copy of your configuration directory is uploaded to Terraform Cloud. You can define a copy of your configuration directory is uploaded to the cloud backend. You can define
paths to exclude from upload by adding a `.terraformignore` file at the root of your paths to exclude from upload by adding a `.terraformignore` file at the root of your
configuration directory. If this file is not present, the upload will exclude configuration directory. If this file is not present, the upload will exclude
the following by default: the following by default:

36
website/docs/cli/code/index.mdx
View File

@ -1,44 +1,34 @@
--- ---
page_title: Writing and Modifying Code - Terraform CLI page_title: Writing and Modifying Code - OpenTF CLI
description: >- description: >-
Learn commands that help validate, format, and upgrade code written in the Learn commands that help validate, format, and upgrade code written in the
Terraform Configuration Language. OpenTF Configuration Language.
--- ---
# Writing and Modifying Terraform Code # Writing and Modifying OpenTF Code
The [Terraform language](/terraform/language) is Terraform's primary The [OpenTF language](/opentf/language) is OpenTF's primary
user interface, and all of Terraform's workflows rely on configurations written user interface, and all of OpenTF's workflows rely on configurations written
in the Terraform language. in the OpenTF language.
Terraform CLI includes several commands to make Terraform code more convenient OpenTF CLI includes several commands to make OpenTF code more convenient
to work with. Integrating these commands into your editing workflow can to work with. Integrating these commands into your editing workflow can
potentially save you time and effort. potentially save you time and effort.
- [The `terraform console` command](/terraform/cli/commands/console) starts an - [The `opentf console` command](/opentf/cli/commands/console) starts an
interactive shell for evaluating Terraform interactive shell for evaluating OpenTF
[expressions](/terraform/language/expressions), which can be a faster way [expressions](/opentf/language/expressions), which can be a faster way
to verify that a particular resource argument results in the value you expect. to verify that a particular resource argument results in the value you expect.
- [The `terraform fmt` command](/terraform/cli/commands/fmt) rewrites Terraform - [The `opentf fmt` command](/opentf/cli/commands/fmt) rewrites OpenTF
configuration files to a canonical format and style, so you don't have to configuration files to a canonical format and style, so you don't have to
waste time making minor adjustments for readability and consistency. It works waste time making minor adjustments for readability and consistency. It works
well as a pre-commit hook in your version control system. well as a pre-commit hook in your version control system.
- [The `terraform validate` command](/terraform/cli/commands/validate) validates the - [The `opentf validate` command](/opentf/cli/commands/validate) validates the
syntax and arguments of the Terraform configuration files in a directory, syntax and arguments of the OpenTF configuration files in a directory,
including argument and attribute names and types for resources and modules. including argument and attribute names and types for resources and modules.
The `plan` and `apply` commands automatically validate a configuration before The `plan` and `apply` commands automatically validate a configuration before
performing any other work, so `validate` isn't a crucial part of the core performing any other work, so `validate` isn't a crucial part of the core
workflow, but it can be very useful as a pre-commit hook or as part of a workflow, but it can be very useful as a pre-commit hook or as part of a
continuous integration pipeline. continuous integration pipeline.
- [The `0.13upgrade` command](/terraform/cli/commands/0.13upgrade) and
[the `0.12upgrade` command](/terraform/cli/commands/0.12upgrade) can automatically
modify the configuration files in a Terraform module to help deal with major
syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both
of these commands are only available in the Terraform version they are
associated with, and you are expected to upgrade older code to be compatible
with 0.12 before attempting to make it compatible with 0.13. For more detailed
information about updating code for new Terraform versions, see the [upgrade
guides](/terraform/language/upgrade-guides) in the Terraform language docs.

117
website/docs/cli/commands/0.12upgrade.mdx
View File

@ -1,117 +0,0 @@
---
page_title: 'Command: 0.12upgrade'
description: >-
The 0.12upgrade subcommand automatically rewrites existing configurations for
Terraform 0.12 compatibility.
---
# Command: 0.12upgrade
The `terraform 0.12upgrade` command applies several automatic upgrade rules to
help prepare a module that was written for Terraform v0.11 to be used
with Terraform v0.12.
-> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12).
## Usage
Usage: `terraform 0.12upgrade [options] [dir]`
By default, `0.12upgrade` changes configuration files in the current working
directory. However, you can provide an explicit path to another directory if
desired, which may be useful for automating migrations of several modules in
the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
```
$ terraform 0.12upgrade
This command will rewrite the configuration files in the given directory so
that they use the new syntax features from Terraform v0.12, and will identify
any constructs that may need to be adjusted for correct operation with
Terraform v0.12.
We recommend using this command in a clean version control work tree, so that
you can easily see the proposed changes as a diff against the latest commit.
If you have uncommitted changes already present, we recommend aborting this
command and dealing with them before running this command again.
Would you like to upgrade the module in the current directory?
Only 'yes' will be accepted to confirm.
Enter a value: yes
```
The `0.12upgrade` subcommand requires access to providers used in the
configuration in order to analyze their resource types, so it's important to
run `terraform init` first to install these. In some rare cases, a configuration
that worked in v0.11 may have syntax errors in v0.12, in which case
`terraform init` will run in a special mode where it installs only enough to
run the upgrade command, after which you can run `terraform init` again to
complete initialization.
Many of the rewrite rules are completely automatic, but in some cases the
tool cannot determine enough information from the configuration alone to make
a decision, and so it will instead add a comment to the configuration for
user review. All such comments contain the string `TF-UPGRADE-TODO` to make
them easier to find.
After upgrading, the configuration will also be reformatted into the standard
Terraform style and expressions rewritten to use the more-readable v0.12 syntax
features.
We recommend running this command with a clean version control work tree so
that you can use VCS tools to review the proposed changes, including any
`TF-UPGRADE-TODO` comments, and make any revisions required before committing
the change.
Once upgraded the configuration will no longer be compatible with Terraform
v0.11 and earlier. When upgrading a shared module that is called from multiple
configurations, you may need to
[fix existing configurations to a previous version](/terraform/language/modules/syntax#version)
to allow for a gradual upgrade. If the module is published via
[a Terraform registry](/terraform/registry), assign a new _major_ version number
to the upgraded module source to represent the fact that this is a breaking
change for v0.11 callers. If a module is installed directly from a version
control system such as Git,
[use specific revisions](/terraform/language/modules/sources#selecting-a-revision)
to control which version is used by which caller.
The command-line options are all optional. The available options are:
* `-yes` - Skip the initial introduction messages and interactive confirmation.
Use this when running the command in batch from a script.
* `-force` - Override the heuristic that attempts to detect if a configuration
is already written for v0.12 or later. Some of the transformations made by
this command are not idempotent, so re-running against the same module may
change the meanings of some expressions in the module.
## Batch Usage
After you've experimented with the `0.12upgrade` command in some confined
situations, if you have a repository containing multiple modules you may
wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
```
find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes
```
On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument:
```
brew install findutils
```
Once installed, run the above command line using `gfind` instead of `find`.
Note that the above includes the `-yes` option to override the interactive
prompt, so be sure you have a clean work tree before running it.
Because upgrading requires access to the configuration's provider plugins,
all of the directories must be initialized with `terraform init` prior to
running the above.

89
website/docs/cli/commands/0.13upgrade.mdx
View File

@ -1,89 +0,0 @@
---
page_title: 'Command: 0.13upgrade'
description: >-
The 0.13upgrade subcommand updates existing configurations to use the new
provider source features from Terraform 0.13.
---
# Command: 0.13upgrade
The `terraform 0.13upgrade` command updates existing configuration to add an
explicit `source` attribute for each provider used in a given module. The
provider source settings are stored in a `required_providers` block.
-> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13).
## Usage
Usage: `terraform 0.13upgrade [options] [dir]`
The primary purpose of the `0.13upgrade` command is to determine which
providers are in use for a module, detect the source address for those
providers where possible, and record this information in a
[`required_providers` block][required-providers].
[required-providers]: /terraform/language/providers/requirements
~> Note: the command ignores `.tf.json` files and override files in the module.
If the module already has a `required_providers` block, the command updates it
in-place. Otherwise, a new block is added to the `versions.tf` file.
By default, `0.13upgrade` changes configuration files in the current working
directory. However, you can provide an explicit path to another directory if
desired, which may be useful for automating migrations of several modules in
the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
```
$ terraform 0.13upgrade
This command will update the configuration files in the given directory to use
the new provider source features from Terraform v0.13. It will also highlight
any providers for which the source cannot be detected, and advise how to
proceed.
We recommend using this command in a clean version control work tree, so that
you can easily see the proposed changes as a diff against the latest commit.
If you have uncommited changes already present, we recommend aborting this
command and dealing with them before running this command again.
Would you like to upgrade the module in the current directory?
Only 'yes' will be accepted to confirm.
Enter a value: yes
```
We recommend running this command with a clean version control work tree so
that you can use VCS tools to review the proposed changes, including any
`TF-UPGRADE-TODO` comments, and make any revisions required before committing
the change.
There is one command-line option:
* `-yes` - Skip the initial introduction messages and interactive confirmation.
Use this when running the command in batch from a script.
## Batch Usage
After you've experimented with the `0.13upgrade` command in some confined
situations, if you have a repository containing multiple modules you may
wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
```
$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes
```
On a Windows system with PowerShell, you can use this command:
```
Get-Childitem -Recurse -Include *.tf | Split-Path | `
Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName }
```
Note that the above commands include the `-yes` option to override the
interactive prompt, so be sure you have a clean work tree before running it.

79
website/docs/cli/commands/apply.mdx
View File

@ -1,48 +1,46 @@
--- ---
page_title: 'Command: apply' page_title: 'Command: apply'
description: >- description: >-
The terraform apply command executes the actions proposed in a Terraform plan The opentf apply command executes the actions proposed in a OpenTF plan
to create, update, or destroy infrastructure. to create, update, or destroy infrastructure.
--- ---
# Command: apply # Command: apply
The `terraform apply` command executes the actions proposed in a Terraform The `opentf apply` command executes the actions proposed in a OpenTF
plan. plan.
> **Hands On:** Try the [Apply Terraform Configuration](/terraform/tutorials/cli/apply?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial to learn how Terraform applies a configuration, how Terraform recovers from errors during apply, and common ways to use this command.
## Usage ## Usage
Usage: `terraform apply [options] [plan file]` Usage: `opentf apply [options] [plan file]`
### Automatic Plan Mode ### Automatic Plan Mode
When you run `terraform apply` without passing a saved plan file, Terraform automatically creates a new execution plan as if you had run [`terraform plan`](/terraform/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/terraform/cli/commands/plan#planning-modes) and When you run `opentf apply` without passing a saved plan file, OpenTF automatically creates a new execution plan as if you had run [`opentf plan`](/opentf/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/opentf/cli/commands/plan#planning-modes) and
[planning options](/terraform/cli/commands/plan#planning-options) to customize how Terraform will create the plan. [planning options](/opentf/cli/commands/plan#planning-options) to customize how OpenTF will create the plan.
You can pass the `-auto-approve` option to instruct Terraform to apply the plan without asking for confirmation. You can pass the `-auto-approve` option to instruct OpenTF to apply the plan without asking for confirmation.
!> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your Terraform workflow. This minimizes the risk of unpredictable changes and configuration drift. !> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your OpenTF workflow. This minimizes the risk of unpredictable changes and configuration drift.
### Saved Plan Mode ### Saved Plan Mode
When you pass a [saved plan file](/terraform/cli/commands/plan#out-filename) to `terraform apply`, Terraform takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when [running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). When you pass a [saved plan file](/opentf/cli/commands/plan#out-filename) to `opentf apply`, OpenTF takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when running OpenTF in automation.
Use [`terraform show`](/terraform/cli/commands/show) to inspect a saved plan file before applying it. Use [`opentf show`](/opentf/cli/commands/show) to inspect a saved plan file before applying it.
When using a saved plan, you cannot specify any additional planning modes or options. These options only affect Terraform's decisions about which When using a saved plan, you cannot specify any additional planning modes or options. These options only affect OpenTF's decisions about which
actions to take, and the plan file contains the final results of those actions to take, and the plan file contains the final results of those
decisions. decisions.
### Plan Options ### Plan Options
Without a saved plan file, `terraform apply` supports all planning modes and planning options available for `terraform plan`. Without a saved plan file, `opentf apply` supports all planning modes and planning options available for `opentf plan`.
- **[Planning Modes](/terraform/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update Terraform state and root module output values. - **[Planning Modes](/opentf/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update OpenTF state and root module output values.
- **[Planning Options](/terraform/cli/commands/plan#planning-options):** These include specifying which resource instances Terraform should replace, setting Terraform input variables, etc. - **[Planning Options](/opentf/cli/commands/plan#planning-options):** These include specifying which resource instances OpenTF should replace, setting OpenTF input variables, etc.
### Apply Options ### Apply Options
@ -50,7 +48,7 @@ The following options change how the apply command executes and reports on the a
- `-auto-approve` - Skips interactive approval of plan before applying. This - `-auto-approve` - Skips interactive approval of plan before applying. This
option is ignored when you pass a previously-saved plan file, because option is ignored when you pass a previously-saved plan file, because
Terraform considers you passing the plan file as the approval and so OpenTF considers you passing the plan file as the approval and so
will never prompt in that case. will never prompt in that case.
- `-compact-warnings` - Shows any warning messages in a compact form which - `-compact-warnings` - Shows any warning messages in a compact form which
@ -58,63 +56,48 @@ The following options change how the apply command executes and reports on the a
at least one error and thus the warning text might be useful context for at least one error and thus the warning text might be useful context for
the errors. the errors.
- `-input=false` - Disables all of Terraform's interactive prompts. Note that - `-input=false` - Disables all of OpenTF's interactive prompts. Note that
this also prevents Terraform from prompting for interactive approval of a this also prevents OpenTF from prompting for interactive approval of a
plan, so Terraform will conservatively assume that you do not wish to plan, so OpenTF will conservatively assume that you do not wish to
apply the plan, causing the operation to fail. If you wish to run Terraform apply the plan, causing the operation to fail.
in a non-interactive context, see
[Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) for some
different approaches.
- `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output. - `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output.
This implies `-input=false`, so the configuration must have no unassigned This implies `-input=false`, so the configuration must have no unassigned
variable values to continue. To enable this flag, you must also either enable variable values to continue. To enable this flag, you must also either enable
the `-auto-approve` flag or specify a previously-saved plan. the `-auto-approve` flag or specify a previously-saved plan.
[machine-readable-ui]: /terraform/internals/machine-readable-ui [machine-readable-ui]: /opentf/internals/machine-readable-ui
- `-lock=false` - Don't hold a state lock during the operation. This is - `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
- `-no-color` - Disables terminal formatting sequences in the output. Use this - `-no-color` - Disables terminal formatting sequences in the output. Use this
if you are running Terraform in a context where its output will be if you are running OpenTF in a context where its output will be
rendered by a system that cannot interpret terminal formatting. rendered by a system that cannot interpret terminal formatting.
- `-parallelism=n` - Limit the number of concurrent operation as Terraform - `-parallelism=n` - Limit the number of concurrent operation as OpenTF
[walks the graph](/terraform/internals/graph#walking-the-graph). Defaults to [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults to
10\. 10\.
- All [planning modes](/terraform/cli/commands/plan#planning-modes) and - All [planning modes](/opentf/cli/commands/plan#planning-modes) and
[planning options](/terraform/cli/commands/plan#planning-options) for [planning options](/opentf/cli/commands/plan#planning-options) for
`terraform plan` - Customize how Terraform will create the plan. Only available when you run `terraform apply` without a saved plan file. `opentf plan` - Customize how OpenTF will create the plan. Only available when you run `opentf apply` without a saved plan file.
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform apply` also accepts the legacy options `opentf apply` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).
## Passing a Different Configuration Directory ## Passing a Different Configuration Directory
Terraform v0.13 and earlier also accepted a directory path in place of the
plan file argument to `terraform apply`, in which case Terraform would use
that directory as the root module instead of the current working directory.
That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15.
If your workflow relies on overriding the root module directory, use If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) [the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look 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 in the given directory for all files it would normally read or write in the
current working directory. current working directory.
If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other
than the current working directory.

34
website/docs/cli/commands/console.mdx
View File

@ -1,44 +1,44 @@
--- ---
page_title: 'Command: console' page_title: 'Command: console'
description: >- description: >-
The terraform console command provides an interactive console for evaluating The opentf console command provides an interactive console for evaluating
expressions. expressions.
--- ---
# Command: console # Command: console
The `terraform console` command provides an interactive console for The `opentf console` command provides an interactive console for
evaluating [expressions](/terraform/language/expressions). evaluating [expressions](/opentf/language/expressions).
## Usage ## Usage
Usage: `terraform console [options]` Usage: `opentf console [options]`
This command provides an interactive command-line console for evaluating and This command provides an interactive command-line console for evaluating and
experimenting with [expressions](/terraform/language/expressions). experimenting with [expressions](/opentf/language/expressions).
You can use it to test interpolations before using them in configurations You can use it to test interpolations before using them in configurations
and to interact with any values currently saved in and to interact with any values currently saved in
[state](/terraform/language/state). If the current state is empty or has not yet been created, you can use the console to experiment with the expression syntax and [state](/opentf/language/state). If the current state is empty or has not yet been created, you can use the console to experiment with the expression syntax and
[built-in functions](/terraform/language/functions). The console holds a [lock on the state](/terraform/language/state/locking), and you will not be able to use the console while performing other actions that modify state. [built-in functions](/opentf/language/functions). The console holds a [lock on the state](/opentf/language/state/locking), and you will not be able to use the console while performing other actions that modify state.
To close the console, enter the `exit` command or press Control-C To close the console, enter the `exit` command or press Control-C
or Control-D. or Control-D.
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform console` accepts the legacy command line option `opentf console` accepts the legacy command line option
[`-state`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`](/opentf/language/settings/backends/local#command-line-arguments).
## Scripting ## Scripting
The `terraform console` command can be used in non-interactive scripts The `opentf console` command can be used in non-interactive scripts
by piping newline-separated commands to it. Only the output from the by piping newline-separated commands to it. Only the output from the
final command is printed unless an error occurs earlier. final command is printed unless an error occurs earlier.
For example: For example:
```shell ```shell
$ echo 'split(",", "foo,bar,baz")' | terraform console $ echo 'split(",", "foo,bar,baz")' | opentf console
tolist([ tolist([
"foo", "foo",
"bar", "bar",
@ -48,14 +48,14 @@ tolist([
## Remote State ## Remote State
If [remote state](/terraform/language/state/remote) is used by the current backend, If [remote state](/opentf/language/state/remote) is used by the current backend,
Terraform will read the state for the current workspace from the backend OpenTF will read the state for the current workspace from the backend
before evaluating any expressions. before evaluating any expressions.
## Examples ## Examples
The `terraform console` command will read the Terraform configuration in the The `opentf console` command will read the OpenTF configuration in the
current working directory and the Terraform state file from the configured current working directory and the OpenTF state file from the configured
backend so that interpolations can be tested against both the values in the backend so that interpolations can be tested against both the values in the
configuration and the state file. configuration and the state file.
@ -82,7 +82,7 @@ resource "random_pet" "example" {
} }
``` ```
Executing `terraform console` will drop you into an interactive shell where you Executing `opentf console` will drop you into an interactive shell where you
can test interpolations to: can test interpolations to:
Print a value from a map: Print a value from a map:

24
website/docs/cli/commands/destroy.mdx
View File

@ -1,33 +1,33 @@
--- ---
page_title: 'Command: destroy' page_title: 'Command: destroy'
description: >- description: >-
The terraform destroy command destroys all objects managed by a Terraform The opentf destroy command destroys all objects managed by a OpenTF
configuration. configuration.
--- ---
# Command: destroy # Command: destroy
The `terraform destroy` command is a convenient way to destroy all remote The `opentf destroy` command is a convenient way to destroy all remote
objects managed by a particular Terraform configuration. objects managed by a particular OpenTF configuration.
While you will typically not want to destroy long-lived objects in a production While you will typically not want to destroy long-lived objects in a production
environment, Terraform is sometimes used to manage ephemeral infrastructure environment, OpenTF is sometimes used to manage ephemeral infrastructure
for development purposes, in which case you can use `terraform destroy` to for development purposes, in which case you can use `opentf destroy` to
conveniently clean up all of those temporary objects once you are finished conveniently clean up all of those temporary objects once you are finished
with your work. with your work.
## Usage ## Usage
Usage: `terraform destroy [options]` Usage: `opentf destroy [options]`
This command is just a convenience alias for the following command: This command is just a convenience alias for the following command:
``` ```
terraform apply -destroy opentf apply -destroy
``` ```
For that reason, this command accepts most of the options that For that reason, this command accepts most of the options that
[`terraform apply`](/terraform/cli/commands/apply) accepts, although it does [`opentf apply`](/opentf/cli/commands/apply) accepts, although it does
not accept a plan file argument and forces the selection of the "destroy" not accept a plan file argument and forces the selection of the "destroy"
planning mode. planning mode.
@ -35,12 +35,8 @@ You can also create a speculative destroy plan, to see what the effect of
destroying would be, by running the following command: destroying would be, by running the following command:
``` ```
terraform plan -destroy opentf plan -destroy
``` ```
This will run [`terraform plan`](/terraform/cli/commands/plan) in _destroy_ mode, showing This will run [`opentf plan`](/opentf/cli/commands/plan) in _destroy_ mode, showing
you the proposed destroy changes without executing them. you the proposed destroy changes without executing them.
-> **Note:** The `-destroy` option to `terraform apply` exists only in
Terraform v0.15.2 and later. For earlier versions, you _must_ use
`terraform destroy` to get the effect of `terraform apply -destroy`.

6
website/docs/cli/commands/env.mdx
View File

@ -1,12 +1,12 @@
--- ---
page_title: 'Command: env' page_title: 'Command: env'
description: >- description: >-
The terraform env command is a deprecated form of the terraform workspace The opentf env command is a deprecated form of the opentf workspace
command. command.
--- ---
# Command: env # Command: env
The `terraform env` command is deprecated. The `opentf env` command is deprecated.
[The `terraform workspace` command](/terraform/cli/commands/workspace) [The `opentf workspace` command](/opentf/cli/commands/workspace)
should be used instead. should be used instead.

34
website/docs/cli/commands/fmt.mdx
View File

@ -1,51 +1,51 @@
--- ---
page_title: 'Command: fmt' page_title: 'Command: fmt'
description: >- description: >-
The terraform fmt command rewrites configuration files to a canonical format The opentf fmt command rewrites configuration files to a canonical format
and style. and style.
--- ---
# Command: fmt # Command: fmt
The `terraform fmt` command is used to rewrite Terraform configuration files The `opentf fmt` command is used to rewrite OpenTF configuration files
to a canonical format and style. This command applies a subset of to a canonical format and style. This command applies a subset of
the [Terraform language style conventions](/terraform/language/syntax/style), the [OpenTF language style conventions](/opentf/language/syntax/style),
along with other minor adjustments for readability. along with other minor adjustments for readability.
Other Terraform commands that generate Terraform configuration will produce Other OpenTF commands that generate OpenTF configuration will produce
configuration files that conform to the style imposed by `terraform fmt`, so configuration files that conform to the style imposed by `opentf fmt`, so
using this style in your own files will ensure consistency. using this style in your own files will ensure consistency.
The canonical format may change in minor ways between Terraform versions, so The canonical format may change in minor ways between OpenTF versions, so
after upgrading Terraform we recommend to proactively run `terraform fmt` after upgrading OpenTF we recommend to proactively run `opentf fmt`
on your modules along with any other changes you are making to adopt the new on your modules along with any other changes you are making to adopt the new
version. version.
We don't consider new formatting rules in `terraform fmt` to be a breaking We don't consider new formatting rules in `opentf fmt` to be a breaking
change in new versions of Terraform, but we do aim to minimize changes for change in new versions of OpenTF, but we do aim to minimize changes for
configurations that are already following the style examples shown in the configurations that are already following the style examples shown in the
Terraform documentation. When adding new formatting rules, they will usually OpenTF documentation. When adding new formatting rules, they will usually
aim to apply more of the rules already shown in the configuration examples aim to apply more of the rules already shown in the configuration examples
in the documentation, and so we recommend following the documented style even in the documentation, and so we recommend following the documented style even
for decisions that `terraform fmt` doesn't yet apply automatically. for decisions that `opentf fmt` doesn't yet apply automatically.
Formatting decisions are always subjective and so you might disagree with the Formatting decisions are always subjective and so you might disagree with the
decisions that `terraform fmt` makes. This command is intentionally opinionated decisions that `opentf fmt` makes. This command is intentionally opinionated
and has no customization options because its primary goal is to encourage and has no customization options because its primary goal is to encourage
consistency of style between different Terraform codebases, even though the consistency of style between different OpenTF codebases, even though the
chosen style can never be everyone's favorite. chosen style can never be everyone's favorite.
We recommend that you follow the style conventions applied by `terraform fmt` We recommend that you follow the style conventions applied by `opentf fmt`
when writing Terraform modules, but if you find the results particularly when writing OpenTF modules, but if you find the results particularly
objectionable then you may choose not to use this command, and possibly choose objectionable then you may choose not to use this command, and possibly choose
to use a third-party formatting tool instead. If you choose to use a to use a third-party formatting tool instead. If you choose to use a
third-party tool then you should also run it on files that are generated third-party tool then you should also run it on files that are generated
automatically by Terraform, to get consistency between your hand-written files automatically by OpenTF, to get consistency between your hand-written files
and the generated files. and the generated files.
## Usage ## Usage
Usage: `terraform fmt [options] [target...]` Usage: `opentf fmt [options] [target...]`
By default, `fmt` scans the current directory for configuration files. If you By default, `fmt` scans the current directory for configuration files. If you
provide a directory for the `target` argument, then `fmt` will scan that provide a directory for the `target` argument, then `fmt` will scan that

4
website/docs/cli/commands/force-unlock.mdx
View File

@ -1,7 +1,7 @@
--- ---
page_title: 'Command: force-unlock' page_title: 'Command: force-unlock'
description: >- description: >-
The terraform force-unlock command unlocks the state for a configuration. It The opentf force-unlock command unlocks the state for a configuration. It
does not modify your infrastructure. does not modify your infrastructure.
--- ---
@ -16,7 +16,7 @@ process.
## Usage ## Usage
Usage: `terraform force-unlock [options] LOCK_ID` Usage: `opentf force-unlock [options] LOCK_ID`
Manually unlock the state for the defined configuration. Manually unlock the state for the defined configuration.

8
website/docs/cli/commands/get.mdx
View File

@ -1,16 +1,16 @@
--- ---
page_title: 'Command: get' page_title: 'Command: get'
description: The terraform get command downloads and updates modules. description: The opentf get command downloads and updates modules.
--- ---
# Command: get # Command: get
The `terraform get` command is used to download and update The `opentf get` command is used to download and update
[modules](/terraform/language/modules/develop) mentioned in the root module. [modules](/opentf/language/modules/develop) mentioned in the root module.
## Usage ## Usage
Usage: `terraform get [options]` Usage: `opentf get [options]`
The modules are downloaded into a `.terraform` subdirectory of the current The modules are downloaded into a `.terraform` subdirectory of the current
working directory. Don't commit this directory to your version control working directory. Don't commit this directory to your version control

16
website/docs/cli/commands/graph.mdx
View File

@ -1,29 +1,29 @@
--- ---
page_title: 'Command: graph' page_title: 'Command: graph'
description: >- description: >-
The terraform graph command generates a visual representation of a The opentf graph command generates a visual representation of a
configuration or execution plan that you can use to generate charts. configuration or execution plan that you can use to generate charts.
--- ---
# Command: graph # Command: graph
The `terraform graph` command is used to generate a visual The `opentf graph` command is used to generate a visual
representation of either a configuration or execution plan. representation of either a configuration or execution plan.
The output is in the DOT format, which can be used by The output is in the DOT format, which can be used by
[GraphViz](http://www.graphviz.org) to generate charts. [GraphViz](http://www.graphviz.org) to generate charts.
## Usage ## Usage
Usage: `terraform graph [options]` Usage: `opentf graph [options]`
Outputs the visual execution graph of Terraform resources according to Outputs the visual execution graph of OpenTF resources according to
either the current configuration or an execution plan. either the current configuration or an execution plan.
The graph is outputted in DOT format. The typical program that can The graph is outputted in DOT format. The typical program that can
read this format is GraphViz, but many web services are also available read this format is GraphViz, but many web services are also available
to read this format. to read this format.
The `-type` flag can be used to control the type of graph shown. Terraform The `-type` flag can be used to control the type of graph shown. OpenTF
creates different graphs for different operations. See the options below creates different graphs for different operations. See the options below
for the list of types supported. The default type is "plan" if a for the list of types supported. The default type is "plan" if a
configuration is given, and "apply" if a plan file is passed as an configuration is given, and "apply" if a plan file is passed as an
@ -39,17 +39,17 @@ Options:
* `-type=plan` - Type of graph to output. Can be: `plan`, `plan-refresh-only`, `plan-destroy`, or `apply`. * `-type=plan` - Type of graph to output. Can be: `plan`, `plan-refresh-only`, `plan-destroy`, or `apply`.
* `-module-depth=n` - (deprecated) In prior versions of Terraform, specified the * `-module-depth=n` - (deprecated) In prior versions of OpenTF, specified the
depth of modules to show in the output. depth of modules to show in the output.
## Generating Images ## Generating Images
The output of `terraform graph` is in the DOT format, which can The output of `opentf graph` is in the DOT format, which can
easily be converted to an image by making use of `dot` provided easily be converted to an image by making use of `dot` provided
by GraphViz: by GraphViz:
```shellsession ```shellsession
$ terraform graph | dot -Tsvg > graph.svg $ opentf graph | dot -Tsvg > graph.svg
``` ```
Here is an example graph output: Here is an example graph output:

82
website/docs/cli/commands/import.mdx
View File

@ -1,23 +1,21 @@
--- ---
page_title: 'Command: import' page_title: 'Command: import'
description: The terraform import command brings existing resources into Terraform state. description: The opentf import command brings existing resources into OpenTF state.
--- ---
# Command: import # Command: import
> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. The `opentf import` command [imports existing resources](/opentf/cli/import)
into OpenTF.
The `terraform import` command [imports existing resources](/terraform/cli/import)
into Terraform.
## Usage ## Usage
Usage: `terraform import [options] ADDRESS ID` Usage: `opentf import [options] ADDRESS ID`
Import will find the existing resource from ID and import it into your Terraform Import will find the existing resource from ID and import it into your OpenTF
state at the given ADDRESS. state at the given ADDRESS.
ADDRESS must be a valid [resource address](/terraform/cli/state/resource-addressing). ADDRESS must be a valid [resource address](/opentf/cli/state/resource-addressing).
Because any resource address is valid, the import command can import resources Because any resource address is valid, the import command can import resources
into modules as well as directly into the root of your state. into modules as well as directly into the root of your state.
@ -27,19 +25,19 @@ it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentatio
on the ID format. If you're unsure, feel free to just try an ID. If the ID on the ID format. If you're unsure, feel free to just try an ID. If the ID
is invalid, you'll just receive an error message. is invalid, you'll just receive an error message.
~> Warning: Terraform expects that each remote object it is managing will be ~> Warning: OpenTF expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by Terraform bound to only one resource address, which is normally guaranteed by OpenTF
itself having created all objects. If you import existing objects into Terraform, itself having created all objects. If you import existing objects into OpenTF,
be careful to import each remote object to only one Terraform resource address. be careful to import each remote object to only one OpenTF resource address.
If you import the same object multiple times, Terraform may exhibit unwanted If you import the same object multiple times, OpenTF may exhibit unwanted
behavior. For more information on this assumption, see behavior. For more information on this assumption, see
[the State section](/terraform/language/state). [the State section](/opentf/language/state).
The command-line flags are all optional. The following flags are available: The command-line flags are all optional. The following flags are available:
- `-config=path` - Path to directory of Terraform configuration files that - `-config=path` - Path to directory of OpenTF configuration files that
configure the provider for import. This defaults to your working directory. configure the provider for import. This defaults to your working directory.
If this directory contains no Terraform configuration files, the provider If this directory contains no OpenTF configuration files, the provider
must be configured via manual input or environmental variables. must be configured via manual input or environmental variables.
- `-input=true` - Whether to ask for input for provider configuration. - `-input=true` - Whether to ask for input for provider configuration.
@ -52,21 +50,21 @@ The command-line flags are all optional. The following flags are available:
- `-no-color` - If specified, output won't contain any color. - `-no-color` - If specified, output won't contain any color.
- `-parallelism=n` - Limit the number of concurrent operation as Terraform - `-parallelism=n` - Limit the number of concurrent operation as OpenTF
[walks the graph](/terraform/internals/graph#walking-the-graph). Defaults [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults
to 10. to 10.
- `-provider=provider` - **Deprecated** Override the provider configuration to - `-provider=provider` - **Deprecated** Override the provider configuration to
use when importing the object. By default, Terraform uses the provider specified use when importing the object. By default, OpenTF uses the provider specified
in the configuration for the target resource, and that is the best behavior in most cases. in the configuration for the target resource, and that is the best behavior in most cases.
- `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag - `-var 'foo=bar'` - Set a variable in the OpenTF configuration. This flag
can be set multiple times. Variable values are interpreted as can be set multiple times. Variable values are interpreted as
[literal expressions](/terraform/language/expressions/types) in the [literal expressions](/opentf/language/expressions/types) in the
Terraform language, so list and map values can be specified via this flag. OpenTF language, so list and map values can be specified via this flag.
- `-var-file=foo` - Set variables in the Terraform configuration from - `-var-file=foo` - Set variables in the OpenTF configuration from
a [variable file](/terraform/language/values/variables#variable-definitions-tfvars-files). If a [variable file](/opentf/language/values/variables#variable-definitions-tfvars-files). If
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
directory, they will be automatically loaded. `terraform.tfvars` is loaded directory, they will be automatically loaded. `terraform.tfvars` is loaded
first and the `.auto.tfvars` files after in alphabetical order. Any files first and the `.auto.tfvars` files after in alphabetical order. Any files
@ -74,31 +72,31 @@ The command-line flags are all optional. The following flags are available:
the working directory. This flag can be used multiple times. This is only the working directory. This flag can be used multiple times. This is only
useful with the `-config` flag. useful with the `-config` flag.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform import` only, `opentf import`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform import` also accepts the legacy options `opentf import` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).
## Provider Configuration ## Provider Configuration
Terraform will attempt to load configuration files that configure the OpenTF will attempt to load configuration files that configure the
provider being used for import. If no configuration files are present or provider being used for import. If no configuration files are present or
no configuration for that specific provider is present, Terraform will no configuration for that specific provider is present, OpenTF will
prompt you for access credentials. You may also specify environmental variables prompt you for access credentials. You may also specify environmental variables
to configure the provider. to configure the provider.
The only limitation Terraform has when reading the configuration files The only limitation OpenTF has when reading the configuration files
is that the import provider configurations must not depend on non-variable is that the import provider configurations must not depend on non-variable
inputs. For example, a provider configuration cannot depend on a data inputs. For example, a provider configuration cannot depend on a data
source. source.
As a working example, if you're importing AWS resources and you have a As a working example, if you're importing AWS resources and you have a
configuration file with the contents below, then Terraform will configure configuration file with the contents below, then OpenTF will configure
the AWS provider with this file. the AWS provider with this file.
```hcl ```hcl
@ -116,7 +114,7 @@ provider "aws" {
This example will import an AWS instance into the `aws_instance` resource named `foo`: This example will import an AWS instance into the `aws_instance` resource named `foo`:
```shell ```shell
$ terraform import aws_instance.foo i-abcd1234 $ opentf import aws_instance.foo i-abcd1234
``` ```
## Example: Import into Module ## Example: Import into Module
@ -124,37 +122,37 @@ $ terraform import aws_instance.foo i-abcd1234
The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`: The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`:
```shell ```shell
$ terraform import module.foo.aws_instance.bar i-abcd1234 $ opentf import module.foo.aws_instance.bar i-abcd1234
``` ```
## Example: Import into Resource configured with count ## Example: Import into Resource configured with count
The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with
[`count`](/terraform/language/meta-arguments/count): [`count`](/opentf/language/meta-arguments/count):
```shell ```shell
$ terraform import 'aws_instance.baz[0]' i-abcd1234 $ opentf import 'aws_instance.baz[0]' i-abcd1234
``` ```
## Example: Import into Resource configured with for_each ## Example: Import into Resource configured with for_each
The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with
[`for_each`](/terraform/language/meta-arguments/for_each): [`for_each`](/opentf/language/meta-arguments/for_each):
Linux, Mac OS, and UNIX: Linux, Mac OS, and UNIX:
```shell ```shell
$ terraform import 'aws_instance.baz["example"]' i-abcd1234 $ opentf import 'aws_instance.baz["example"]' i-abcd1234
``` ```
PowerShell: PowerShell:
```shell ```shell
$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234 $ opentf import 'aws_instance.baz[\"example\"]' i-abcd1234
``` ```
Windows `cmd.exe`: Windows `cmd.exe`:
```shell ```shell
$ terraform import aws_instance.baz[\"example\"] i-abcd1234 $ opentf import aws_instance.baz[\"example\"] i-abcd1234
``` ```

63
website/docs/cli/commands/index.mdx
View File

@ -1,27 +1,18 @@
--- ---
page_title: Basic CLI Features page_title: Basic CLI Features
description: An introduction to the terraform command and its available subcommands. description: An introduction to the opentf command and its available subcommands.
--- ---
# Basic CLI Features # Basic CLI Features
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. The command line interface to OpenTF is the `opentf` command, which
accepts a variety of subcommands such as `opentf init` or `opentf plan`.
The command line interface to Terraform is the `terraform` command, which To view a list of the commands available in your current OpenTF version,
accepts a variety of subcommands such as `terraform init` or `terraform plan`. run `opentf` with no additional arguments:
We refer to the `terraform` command line tool as "Terraform CLI" elsewhere
in the documentation. This terminology is often used to distinguish it from
other components you might use in the Terraform product family, such as
[Terraform Cloud](/terraform/cloud-docs) or
the various [Terraform providers](/terraform/language/providers), which
are developed and released separately from Terraform CLI.
To view a list of the commands available in your current Terraform version,
run `terraform` with no additional arguments:
```text ```text
Usage: terraform [global options] <subcommand> [args] Usage: opentf [global options] <subcommand> [args]
The available commands for execution are listed below. The available commands for execution are listed below.
The primary workflow commands are given first, followed by The primary workflow commands are given first, followed by
@ -35,12 +26,12 @@ Main commands:
destroy Destroy previously-created infrastructure destroy Destroy previously-created infrastructure
All other commands: All other commands:
console Try Terraform expressions at an interactive command prompt console Try OpenTF expressions at an interactive command prompt
fmt Reformat your configuration in the standard style fmt Reformat your configuration in the standard style
force-unlock Release a stuck lock on the current workspace force-unlock Release a stuck lock on the current workspace
get Install or upgrade remote Terraform modules get Install or upgrade remote OpenTF modules
graph Generate a Graphviz graph of the steps in an operation graph Generate a Graphviz graph of the steps in an operation
import Associate existing infrastructure with a Terraform resource import Associate existing infrastructure with a OpenTF resource
login Obtain and save credentials for a remote host login Obtain and save credentials for a remote host
logout Remove locally-stored credentials for a remote host logout Remove locally-stored credentials for a remote host
metadata Metadata related commands metadata Metadata related commands
@ -51,7 +42,7 @@ All other commands:
state Advanced state management state Advanced state management
taint Mark a resource instance as not fully functional taint Mark a resource instance as not fully functional
untaint Remove the 'tainted' state from a resource instance untaint Remove the 'tainted' state from a resource instance
version Show the current Terraform version version Show the current OpenTF version
workspace Workspace management workspace Workspace management
Global options (use these before the subcommand, if any): Global options (use these before the subcommand, if any):
@ -61,43 +52,43 @@ Global options (use these before the subcommand, if any):
-version An alias for the "version" subcommand. -version An alias for the "version" subcommand.
``` ```
(The output from your current Terraform version may be different than the (The output from your current OpenTF version may be different than the
above example.) above example.)
To get specific help for any specific command, use the `-help` option with the To get specific help for any specific command, use the `-help` option with the
relevant subcommand. For example, to see help about the "validate" subcommand relevant subcommand. For example, to see help about the "validate" subcommand
you can run `terraform validate -help`. you can run `opentf validate -help`.
The inline help built in to Terraform CLI describes the most important The inline help built in to OpenTF CLI describes the most important
characteristics of each command. For more detailed information, refer to each characteristics of each command. For more detailed information, refer to each
command's page for details. command's page for details.
## Switching working directory with `-chdir` ## Switching working directory with `-chdir`
The usual way to run Terraform is to first switch to the directory containing The usual way to run OpenTF is to first switch to the directory containing
the `.tf` files for your root module (for example, using the `cd` command), so the `.tf` files for your root module (for example, using the `cd` command), so
that Terraform will find those files automatically without any extra arguments. that OpenTF will find those files automatically without any extra arguments.
In some cases though — particularly when wrapping Terraform in automation In some cases though — particularly when wrapping OpenTF in automation
scripts — it can be convenient to run Terraform from a different directory than scripts — it can be convenient to run OpenTF from a different directory than
the root module directory. To allow that, Terraform supports a global option the root module directory. To allow that, OpenTF supports a global option
`-chdir=...` which you can include before the name of the subcommand you intend `-chdir=...` which you can include before the name of the subcommand you intend
to run: to run:
``` ```
terraform -chdir=environments/production apply opentf -chdir=environments/production apply
``` ```
The `chdir` option instructs Terraform to change its working directory to the The `chdir` option instructs OpenTF to change its working directory to the
given directory before running the given subcommand. This means that any files given directory before running the given subcommand. This means that any files
that Terraform would normally read or write in the current working directory that OpenTF would normally read or write in the current working directory
will be read or written in the given directory instead. will be read or written in the given directory instead.
There are two exceptions where Terraform will use the original working directory There are two exceptions where OpenTF will use the original working directory
even when you specify `-chdir=...`: even when you specify `-chdir=...`:
* Settings in the [CLI Configuration](/terraform/cli/config/config-file) are not for a specific * Settings in the [CLI Configuration](/opentf/cli/config/config-file) are not for a specific
subcommand and Terraform processes them before acting on the `-chdir` subcommand and OpenTF processes them before acting on the `-chdir`
option. option.
* In case you need to use files from the original working directory as part * In case you need to use files from the original working directory as part
@ -107,13 +98,13 @@ even when you specify `-chdir=...`:
## Shell Tab-completion ## Shell Tab-completion
If you use either `bash` or `zsh` as your command shell, Terraform can provide If you use either `bash` or `zsh` as your command shell, OpenTF can provide
tab-completion support for all command names and some command arguments. tab-completion support for all command names and some command arguments.
To add the necessary commands to your shell profile, run the following command: To add the necessary commands to your shell profile, run the following command:
```bash ```bash
terraform -install-autocomplete opentf -install-autocomplete
``` ```
After installation, it is necessary to restart your shell or to re-read its After installation, it is necessary to restart your shell or to re-read its
@ -123,5 +114,5 @@ To uninstall the completion hook, assuming that it has not been modified
manually in the shell profile, run the following command: manually in the shell profile, run the following command:
```bash ```bash
terraform -uninstall-autocomplete opentf -uninstall-autocomplete
``` ```

86
website/docs/cli/commands/init.mdx
View File

@ -1,25 +1,23 @@
--- ---
page_title: 'Command: init' page_title: 'Command: init'
description: >- description: >-
The terraform init command initializes a working directory containing The opentf init command initializes a working directory containing
configuration files and installs plugins for required providers. configuration files and installs plugins for required providers.
--- ---
# Command: init # Command: init
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). The `opentf init` command initializes a working directory
containing OpenTF configuration files. This is the first command that should
The `terraform init` command initializes a working directory be run after writing a new OpenTF configuration or cloning an existing one
containing Terraform configuration files. This is the first command that should
be run after writing a new Terraform configuration or cloning an existing one
from version control. It is safe to run this command multiple times. from version control. It is safe to run this command multiple times.
## Usage ## Usage
Usage: `terraform init [options]` Usage: `opentf init [options]`
This command performs several different initialization steps in order to This command performs several different initialization steps in order to
prepare the current working directory for use with Terraform. More details on prepare the current working directory for use with OpenTF. More details on
these are in the sections below, but in most cases it is not necessary to worry these are in the sections below, but in most cases it is not necessary to worry
about these individual steps. about these individual steps.
@ -37,7 +35,7 @@ The following options apply to all of (or several of) the initialization steps:
* `-lock=false` Disable locking of state files during state-related operations. * `-lock=false` Disable locking of state files during state-related operations.
* `-lock-timeout=<duration>` Override the time Terraform will wait to acquire * `-lock-timeout=<duration>` Override the time OpenTF will wait to acquire
a state lock. The default is `0s` (zero seconds), which causes immediate a state lock. The default is `0s` (zero seconds), which causes immediate
failure if the lock is already held by another process. failure if the lock is already held by another process.
@ -48,7 +46,7 @@ The following options apply to all of (or several of) the initialization steps:
## Copy a Source Module ## Copy a Source Module
By default, `terraform init` assumes that the working directory already By default, `opentf init` assumes that the working directory already
contains a configuration and will attempt to initialize that configuration. contains a configuration and will attempt to initialize that configuration.
Optionally, init can be run against an empty directory with the Optionally, init can be run against an empty directory with the
@ -69,12 +67,12 @@ For routine use it is recommended to check out configuration from version
control separately, using the version control system's own commands. This way control separately, using the version control system's own commands. This way
it is possible to pass extra flags to the version control system when necessary, it is possible to pass extra flags to the version control system when necessary,
and to perform other preparation steps (such as configuration generation, or and to perform other preparation steps (such as configuration generation, or
activating credentials) before running `terraform init`. activating credentials) before running `opentf init`.
## Backend Initialization ## Backend Initialization
During init, the root configuration directory is consulted for During init, the root configuration directory is consulted for
[backend configuration](/terraform/language/settings/backends/configuration) and the chosen backend [backend configuration](/opentf/language/settings/backends/configuration) and the chosen backend
is initialized using the given configuration settings. is initialized using the given configuration settings.
Re-running init with an already-initialized backend will update the working Re-running init with an already-initialized backend will update the working
@ -96,14 +94,14 @@ when the working directory was already previously initialized for a particular
backend. backend.
The `-backend-config=...` option can be used for The `-backend-config=...` option can be used for
[partial backend configuration](/terraform/language/settings/backends/configuration#partial-configuration), [partial backend configuration](/opentf/language/settings/backends/configuration#partial-configuration),
in situations where the backend settings are dynamic or sensitive and so cannot in situations where the backend settings are dynamic or sensitive and so cannot
be statically specified in the configuration file. be statically specified in the configuration file.
## Child Module Installation ## Child Module Installation
During init, the configuration is searched for `module` blocks, and the source During init, the configuration is searched for `module` blocks, and the source
code for referenced [modules](/terraform/language/modules/develop) is retrieved from the locations code for referenced [modules](/opentf/language/modules/develop) is retrieved from the locations
given in their `source` arguments. given in their `source` arguments.
Re-running init with modules already installed will install the sources for Re-running init with modules already installed will install the sources for
@ -118,47 +116,40 @@ initialized with its child modules.
## Plugin Installation ## Plugin Installation
Most Terraform providers are published separately from Terraform as plugins. Most OpenTF providers are published separately from OpenTF as plugins.
During init, Terraform searches the configuration for both direct and indirect During init, OpenTF searches the configuration for both direct and indirect
references to providers and attempts to install the plugins for those providers. references to providers and attempts to install the plugins for those providers.
For providers that are published in either For providers that are published in either
[the public Terraform Registry](https://registry.terraform.io/) or in a [the public Terraform Registry](https://registry.terraform.io/) or in a
third-party provider registry, `terraform init` will automatically find, third-party provider registry, `opentf init` will automatically find,
download, and install the necessary provider plugins. If you cannot or do not download, and install the necessary provider plugins. If you cannot or do not
wish to install providers from their origin registries, you can customize how wish to install providers from their origin registries, you can customize how
Terraform installs providers using OpenTF installs providers using
[the provider installation settings in the CLI configuration](/terraform/cli/config/config-file#provider-installation). [the provider installation settings in the CLI configuration](/opentf/cli/config/config-file#provider-installation).
For more information about specifying which providers are required for each For more information about specifying which providers are required for each
of your modules, see [Provider Requirements](/terraform/language/providers/requirements). of your modules, see [Provider Requirements](/opentf/language/providers/requirements).
After successful installation, Terraform writes information about the selected After successful installation, OpenTF writes information about the selected
providers to [the dependency lock file](/terraform/language/files/dependency-lock). providers to [the dependency lock file](/opentf/language/files/dependency-lock).
You should commit this file to your version control system to ensure that You should commit this file to your version control system to ensure that
when you run `terraform init` again in future Terraform will select exactly when you run `opentf init` again in future OpenTF will select exactly
the same provider versions. Use the `-upgrade` option if you want Terraform the same provider versions. Use the `-upgrade` option if you want OpenTF
to ignore the dependency lock file and consider installing newer versions. to ignore the dependency lock file and consider installing newer versions.
You can modify `terraform init`'s plugin behavior with the following options: You can modify `opentf init`'s plugin behavior with the following options:
* `-upgrade` Upgrade all previously-selected plugins to the newest version * `-upgrade` Upgrade all previously-selected plugins to the newest version
that complies with the configuration's version constraints. This will that complies with the configuration's version constraints. This will
cause Terraform to ignore any selections recorded in the dependency lock cause OpenTF to ignore any selections recorded in the dependency lock
file, and to take the newest available version matching the configured file, and to take the newest available version matching the configured
version constraints. version constraints.
* `-get-plugins=false` — Skip plugin installation.
-> Note: Since Terraform 0.13, this option has been superseded by the
[`provider_installation`](/terraform/cli/config/config-file#provider-installation) and
[`plugin_cache_dir`](/terraform/cli/config/config-file#plugin_cache_dir) settings.
It should not be used in Terraform versions 0.13+, and this option
was removed in Terraform 0.15.
* `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from * `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from
the specified directory, as if it had been configured as a `filesystem_mirror` the specified directory, as if it had been configured as a `filesystem_mirror`
in the CLI configuration. If you intend to routinely use a particular in the CLI configuration. If you intend to routinely use a particular
filesystem mirror then we recommend filesystem mirror then we recommend
[configuring Terraform's installation methods globally](/terraform/cli/config/config-file#provider-installation). [configuring OpenTF's installation methods globally](/opentf/cli/config/config-file#provider-installation).
You can use `-plugin-dir` as a one-time override for exceptional situations, You can use `-plugin-dir` as a one-time override for exceptional situations,
such as if you are testing a local build of a provider plugin you are such as if you are testing a local build of a provider plugin you are
currently developing. currently developing.
@ -171,35 +162,22 @@ The valid values for the lockfile mode are as follows:
update the lockfile with third-party dependency management tools, it would be update the lockfile with third-party dependency management tools, it would be
useful to control when it changes explicitly. useful to control when it changes explicitly.
## Running `terraform init` in automation ## Running `opentf init` in automation
For teams that use Terraform as a key part of a change management and For teams that use OpenTF as a key part of a change management and
deployment pipeline, it can be desirable to orchestrate Terraform runs in some deployment pipeline, it can be desirable to orchestrate OpenTF runs in some
sort of automation in order to ensure consistency between runs, and provide sort of automation in order to ensure consistency between runs, and provide
other interesting features such as integration with version control hooks. other interesting features such as integration with version control hooks.
There are some special concerns when running `init` in such an environment, There are some special concerns when running `init` in such an environment,
including optionally making plugins available locally to avoid repeated including optionally making plugins available locally to avoid repeated
re-installation. For more information, see re-installation.
the [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
## Passing a Different Configuration Directory ## Passing a Different Configuration Directory
Terraform v0.13 and earlier also accepted a directory path in place of the If your workflow relies on overriding
plan file argument to `terraform apply`, in which case Terraform would use
that directory as the root module instead of the current working directory.
That usage is still supported in Terraform v0.14, but is now deprecated and removed in
Terraform v0.15. If your workflow relies on overriding
the root module directory, use the root module directory, use
[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) [the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look 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 in the given directory for all files it would normally read or write in the
current working directory. current working directory.
If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other
than the current working directory.

31
website/docs/cli/commands/login.mdx
View File

@ -1,45 +1,40 @@
--- ---
page_title: 'Command: login' page_title: 'Command: login'
description: >- description: >-
The terraform login command can be used to automatically obtain and save an The opentf login command can be used to automatically obtain and save an
API token for Terraform Cloud, Terraform Enterprise, or any other host that API token for any host that offers OpenTF-compatible services.
offers Terraform services.
--- ---
# Command: login # Command: login
The `terraform login` command can be used to automatically obtain and save an The `opentf login` command can be used to automatically obtain and save an
API token for Terraform Cloud, Terraform Enterprise, or any other host that offers Terraform services. API token for any host that offers OpenTF-compatible services.
-> **Note:** This command is suitable only for use in interactive scenarios -> **Note:** This command is suitable only for use in interactive scenarios
where it is possible to launch a web browser on the same host where Terraform where it is possible to launch a web browser on the same host where OpenTF
is running. If you are running Terraform in an unattended automation scenario, is running. If you are running OpenTF in an unattended automation scenario,
you can you can
[configure credentials manually in the CLI configuration](/terraform/cli/config/config-file#credentials). [configure credentials manually in the CLI configuration](/opentf/cli/config/config-file#credentials).
## Usage ## Usage
Usage: `terraform login [hostname]` Usage: `opentf login [hostname]`
If you don't provide an explicit hostname, Terraform will assume you want to
log in to Terraform Cloud at `app.terraform.io`.
## Credentials Storage ## Credentials Storage
By default, Terraform will obtain an API token and save it in plain text in a By default, OpenTF will obtain an API token and save it in plain text in a
local CLI configuration file called `credentials.tfrc.json`. When you run local CLI configuration file called `credentials.tfrc.json`. When you run
`terraform login`, it will explain specifically where it intends to save `opentf login`, it will explain specifically where it intends to save
the API token and give you a chance to cancel if the current configuration is the API token and give you a chance to cancel if the current configuration is
not as desired. not as desired.
If you don't wish to store your API token in the default location, you can If you don't wish to store your API token in the default location, you can
optionally configure a optionally configure a
[credentials helper program](/terraform/cli/config/config-file#credentials-helpers) which knows [credentials helper program](/opentf/cli/config/config-file#credentials-helpers) which knows
how to store and later retrieve credentials in some other system, such as how to store and later retrieve credentials in some other system, such as
your organization's existing secrets management system. your organization's existing secrets management system.
## Login Server Support ## Login Server Support
The `terraform login` command works with any server supporting the The `opentf login` command works with any server supporting the
[login protocol](/terraform/internals/login-protocol), including Terraform Cloud [login protocol](/opentf/internals/login-protocol).
and Terraform Enterprise.

16
website/docs/cli/commands/logout.mdx
View File

@ -1,29 +1,25 @@
--- ---
page_title: 'Command: logout' page_title: 'Command: logout'
description: >- description: >-
The terraform logout command is used to remove credentials stored by terraform The opentf logout command is used to remove credentials stored by opentf
login. login.
--- ---
# Command: logout # Command: logout
The `terraform logout` command is used to remove credentials stored by The `opentf logout` command is used to remove credentials stored by
`terraform login`. These credentials are API tokens for Terraform Cloud, `opentf login`. These credentials are API tokens for any host that offers OpenTF-compatible services.
Terraform Enterprise, or any other host that offers Terraform services.
## Usage ## Usage
Usage: `terraform logout [hostname]` Usage: `opentf logout [hostname]`
If you don't provide an explicit hostname, Terraform will assume you want to
log out of Terraform Cloud at `app.terraform.io`.
-> **Note:** the API token is only removed from local storage, not destroyed on -> **Note:** the API token is only removed from local storage, not destroyed on
the remote server, so it will remain valid until manually revoked. the remote server, so it will remain valid until manually revoked.
## Credentials Storage ## Credentials Storage
By default, Terraform will remove the token stored in plain text in a local CLI By default, OpenTF will remove the token stored in plain text in a local CLI
configuration file called `credentials.tfrc.json`. If you have configured a configuration file called `credentials.tfrc.json`. If you have configured a
[credentials helper program](/terraform/cli/config/config-file#credentials-helpers), Terraform [credentials helper program](/opentf/cli/config/config-file#credentials-helpers), OpenTF
will use the helper's `forget` command to remove it. will use the helper's `forget` command to remove it.

38
website/docs/cli/commands/output.mdx
View File

@ -1,18 +1,18 @@
--- ---
page_title: 'Command: output' page_title: 'Command: output'
description: >- description: >-
The `terraform output` command is used to extract the value of an output The `opentf output` command is used to extract the value of an output
variable from the state file. variable from the state file.
--- ---
# Command: output # Command: output
The `terraform output` command is used to extract the value of The `opentf output` command is used to extract the value of
an output variable from the state file. an output variable from the state file.
## Usage ## Usage
Usage: `terraform output [options] [NAME]` Usage: `opentf output [options] [NAME]`
With no additional arguments, `output` will display all the outputs for With no additional arguments, `output` will display all the outputs for
the root module. If an output `NAME` is specified, only the value of that the root module. If an output `NAME` is specified, only the value of that
@ -23,22 +23,22 @@ The command-line flags are all optional. The following flags are available:
* `-json` - If specified, the outputs are formatted as a JSON object, with * `-json` - If specified, the outputs are formatted as a JSON object, with
a key per output. If `NAME` is specified, only the output specified will be a key per output. If `NAME` is specified, only the output specified will be
returned. This can be piped into tools such as `jq` for further processing. returned. This can be piped into tools such as `jq` for further processing.
* `-raw` - If specified, Terraform will convert the specified output value to a * `-raw` - If specified, OpenTF will convert the specified output value to a
string and print that string directly to the output, without any special string and print that string directly to the output, without any special
formatting. This can be convenient when working with shell scripts, but formatting. This can be convenient when working with shell scripts, but
it only supports string, number, and boolean values. Use `-json` instead it only supports string, number, and boolean values. Use `-json` instead
for processing complex data types. for processing complex data types.
* `-no-color` - If specified, output won't contain any color. * `-no-color` - If specified, output won't contain any color.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
Ignored when [remote state](/terraform/language/state/remote) is used. Ignored when [remote state](/opentf/language/state/remote) is used.
-> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive -> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive
values in Terraform state will be displayed in plain text. For more information, values in OpenTF state will be displayed in plain text. For more information,
see [Sensitive Data in State](/terraform/language/state/sensitive-data). see [Sensitive Data in State](/opentf/language/state/sensitive-data).
## Examples ## Examples
These examples assume the following Terraform output snippet. These examples assume the following OpenTF output snippet.
```hcl ```hcl
output "instance_ips" { output "instance_ips" {
@ -58,7 +58,7 @@ output "password" {
To list all outputs: To list all outputs:
```shellsession ```shellsession
$ terraform output $ opentf output
instance_ips = [ instance_ips = [
"54.43.114.12", "54.43.114.12",
"52.122.13.4", "52.122.13.4",
@ -71,21 +71,21 @@ password = <sensitive>
Note that outputs with the `sensitive` attribute will be redacted: Note that outputs with the `sensitive` attribute will be redacted:
```shellsession ```shellsession
$ terraform output password $ opentf output password
password = <sensitive> password = <sensitive>
``` ```
To query for the DNS address of the load balancer: To query for the DNS address of the load balancer:
```shellsession ```shellsession
$ terraform output lb_address $ opentf output lb_address
"my-app-alb-1657023003.us-east-1.elb.amazonaws.com" "my-app-alb-1657023003.us-east-1.elb.amazonaws.com"
``` ```
To query for all instance IP addresses: To query for all instance IP addresses:
```shellsession ```shellsession
$ terraform output instance_ips $ opentf output instance_ips
instance_ips = [ instance_ips = [
"54.43.114.12", "54.43.114.12",
"52.122.13.4", "52.122.13.4",
@ -95,7 +95,7 @@ instance_ips = [
## Use in automation ## Use in automation
The `terraform output` command by default displays in a human-readable format, The `opentf output` command by default displays in a human-readable format,
which can change over time to improve clarity. which can change over time to improve clarity.
For scripting and automation, use `-json` to produce the stable JSON format. For scripting and automation, use `-json` to produce the stable JSON format.
@ -103,7 +103,7 @@ You can parse the output using a JSON command-line parser such as
[jq](https://stedolan.github.io/jq/): [jq](https://stedolan.github.io/jq/):
```shellsession ```shellsession
$ terraform output -json instance_ips | jq -r '.[0]' $ opentf output -json instance_ips | jq -r '.[0]'
54.43.114.12 54.43.114.12
``` ```
@ -112,15 +112,15 @@ can use `-raw` instead, which will print the string directly with no extra
escaping or whitespace. escaping or whitespace.
```shellsession ```shellsession
$ terraform output -raw lb_address $ opentf output -raw lb_address
my-app-alb-1657023003.us-east-1.elb.amazonaws.com my-app-alb-1657023003.us-east-1.elb.amazonaws.com
``` ```
The `-raw` option works only with values that Terraform can automatically The `-raw` option works only with values that OpenTF can automatically
convert to strings. Use `-json` instead, possibly combined with `jq`, to convert to strings. Use `-json` instead, possibly combined with `jq`, to
work with complex-typed values such as objects. work with complex-typed values such as objects.
Terraform strings are sequences of Unicode characters rather than raw bytes, OpenTF strings are sequences of Unicode characters rather than raw bytes,
so the `-raw` output will be UTF-8 encoded when it contains non-ASCII so the `-raw` output will be UTF-8 encoded when it contains non-ASCII
characters. If you need a different character encoding, use a separate command characters. If you need a different character encoding, use a separate command
such as `iconv` to transcode Terraform's raw output. such as `iconv` to transcode OpenTF's raw output.

193
website/docs/cli/commands/plan.mdx
View File

@ -1,45 +1,42 @@
--- ---
page_title: 'Command: plan' page_title: 'Command: plan'
description: >- description: >-
The terraform plan command creates an execution plan with a preview of the The opentf plan command creates an execution plan with a preview of the
changes that Terraform will make to your infrastructure. changes that OpenTF will make to your infrastructure.
--- ---
# Command: plan # Command: plan
The `terraform plan` command creates an execution plan, which lets you preview The `opentf plan` command creates an execution plan, which lets you preview
the changes that Terraform plans to make to your infrastructure. By default, the changes that OpenTF plans to make to your infrastructure. By default,
when Terraform creates a plan it: when OpenTF creates a plan it:
* Reads the current state of any already-existing remote objects to make sure * Reads the current state of any already-existing remote objects to make sure
that the Terraform state is up-to-date. that the OpenTF state is up-to-date.
* Compares the current configuration to the prior state and noting any * Compares the current configuration to the prior state and noting any
differences. differences.
* Proposes a set of change actions that should, if applied, make the remote * Proposes a set of change actions that should, if applied, make the remote
objects match the configuration. objects match the configuration.
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `plan` command, check out the [Create a Terraform Plan tutorial](/terraform/tutorials/cli/plan?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
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 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 you expected before you apply the changes or share your changes with your
team for broader review. team for broader review.
If Terraform detects that no changes are needed to resource instances or to If OpenTF detects that no changes are needed to resource instances or to
root module output values, `terraform plan` will report that no actions need root module output values, `opentf plan` will report that no actions need
to be taken. to be taken.
If you are using Terraform directly in an interactive terminal and you expect If you are using OpenTF directly in an interactive terminal and you expect
to apply the changes Terraform proposes, you can alternatively run to apply the changes OpenTF proposes, you can alternatively run
[`terraform apply`](/terraform/cli/commands/apply) directly. By default, the "apply" command [`opentf apply`](/opentf/cli/commands/apply) directly. By default, the "apply" command
automatically generates a new plan and prompts for you to approve it. 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 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 file on disk, which you can later execute by passing the file to
[`terraform apply`](/terraform/cli/commands/apply) as an extra argument. This two-step workflow [`opentf apply`](/opentf/cli/commands/apply) as an extra argument. This two-step workflow
is primarily intended for when is primarily intended for when running OpenTF in automation.
[running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
If you run `terraform plan` without the `-out=FILE` option then it will create 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 a _speculative plan_, which is a description of the effect of the plan but
without any intent to actually apply it. without any intent to actually apply it.
@ -54,15 +51,15 @@ matches your intent.
## Usage ## Usage
Usage: `terraform plan [options]` Usage: `opentf plan [options]`
The `plan` subcommand looks in the current working directory for the root module The `plan` subcommand looks in the current working directory for the root module
configuration. configuration.
Because the plan command is one of the main commands of Terraform, it has 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, 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 most of the time you should not need to set any of these options, because
a Terraform configuration should typically be designed to work with no special a OpenTF configuration should typically be designed to work with no special
additional options for routine work. additional options for routine work.
The remaining sections on this page describe the various options: The remaining sections on this page describe the various options:
@ -81,97 +78,87 @@ The remaining sections on this page describe the various options:
## Planning Modes ## Planning Modes
The previous section describes Terraform's default planning behavior, which The previous section describes OpenTF's default planning behavior, which
changes the remote system to match the changes you make to changes the remote system to match the changes you make to
your configuration. Terraform has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `terraform plan` and [`terraform apply`](/terraform/cli/commands/apply). 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 * **Destroy mode:** creates a plan whose goal is to destroy all remote objects
that currently exist, leaving an empty Terraform state. It is the same as running [`terraform destroy`](/terraform/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. 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. Activate destroy mode using the `-destroy` command line option.
* **Refresh-only mode:** creates a plan whose goal is only to update the * **Refresh-only mode:** creates a plan whose goal is only to update the
Terraform state and any root module output values to match changes made to OpenTF state and any root module output values to match changes made to
remote objects outside of Terraform. This can be useful if you've remote objects outside of OpenTF. This can be useful if you've
intentionally changed one or more remote objects outside of the usual 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 workflow (e.g. while responding to an incident) and you now need to reconcile
Terraform's records with those changes. OpenTF's records with those changes.
Activate refresh-only mode using the `-refresh-only` command line option. Activate refresh-only mode using the `-refresh-only` command line option.
In situations where we need to discuss the default planning mode that Terraform 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 uses when none of the alternative modes are selected, we refer to it as
"Normal mode". Because these alternative modes are for specialized situations "Normal mode". Because these alternative modes are for specialized situations
only, some other Terraform documentation only discusses the normal planning only, some other OpenTF documentation only discusses the normal planning
mode. mode.
The planning modes are all mutually-exclusive, so activating any non-default 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 planning mode disables the "normal" planning mode, and you can't use more than
one alternative mode at the same time. one alternative mode at the same time.
-> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is
supported only by the `terraform plan` command, and not by the
`terraform apply` command. To create and apply a plan in destroy mode in
earlier versions you must run [`terraform destroy`](/terraform/cli/commands/destroy).
-> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4
and later.
> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial.
## Planning Options ## 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 `terraform plan` and [`terraform apply`](/terraform/cli/commands/apply). 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 - `-refresh=false` - Disables the default behavior of synchronizing the
Terraform 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 Terraform 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. 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 Terraform to plan to replace the - `-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. Terraform 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, and it is only available from Terraform v0.15.2 onwards. For earlier versions, use [`terraform taint`](/terraform/cli/commands/taint) to achieve a similar result. 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 Terraform to focus its planning efforts only - `-target=ADDRESS` - Instructs OpenTF to focus its planning efforts only
on resource instances which match the given address and on any objects that on resource instances which match the given address and on any objects that
those instances depend on. those instances depend on.
-> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details. -> **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 - `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](/terraform/language/values/variables) declared in the [input variable](/opentf/language/values/variables) declared in the
root module of the configuration. Use this option multiple times to set root module of the configuration. Use this option multiple times to set
more than one variable. Refer to more than one variable. Refer to
[Input Variables on the Command Line](#input-variables-on-the-command-line) for more information. [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many - `-var-file=FILENAME` - Sets values for potentially many
[input variables](/terraform/language/values/variables) declared in the [input variables](/opentf/language/values/variables) declared in the
root module of the configuration, using definitions from a root module of the configuration, using definitions from a
["tfvars" file](/terraform/language/values/variables#variable-definitions-tfvars-files). ["tfvars" file](/opentf/language/values/variables#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file. 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 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 module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables) for more information. [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 ### Input Variables on the Command Line
You can use the `-var` command line option to specify values for You can use the `-var` command line option to specify values for
[input variables](/terraform/language/values/variables) declared in your [input variables](/opentf/language/values/variables) declared in your
root module. root module.
However, to do so will require writing a command line that is parsable both However, to do so will require writing a command line that is parsable both
by your chosen command line shell _and_ Terraform, which can be complicated by your chosen command line shell _and_ OpenTF, which can be complicated
for expressions involving lots of quotes and escape sequences. In most cases 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 we recommend using the `-var-file` option instead, and write your actual values
in a separate file so that Terraform can parse them directly, rather than in a separate file so that OpenTF can parse them directly, rather than
interpreting the result of your shell's parsing. interpreting the result of your shell's parsing.
~> **Warning:** Terraform will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`). ~> **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 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 recommend writing the option argument in single quotes `'` to ensure the
shell will interpret the value literally: shell will interpret the value literally:
``` ```
terraform plan -var 'name=value' opentf plan -var 'name=value'
``` ```
If your intended value also includes a single quote then you'll still need to If your intended value also includes a single quote then you'll still need to
@ -180,82 +167,80 @@ temporarily ending the quoted sequence so that the backslash escape character
will be significant: will be significant:
``` ```
terraform plan -var 'name=va'\''lue' opentf plan -var 'name=va'\''lue'
``` ```
When using Terraform on Windows, we recommend using the Windows Command Prompt When using OpenTF on Windows, we recommend using the Windows Command Prompt
(`cmd.exe`). When you pass a variable value to Terraform from the Windows (`cmd.exe`). When you pass a variable value to OpenTF from the Windows
Command Prompt, use double quotes `"` around the argument: Command Prompt, use double quotes `"` around the argument:
``` ```
terraform plan -var "name=value" opentf plan -var "name=value"
``` ```
If your intended value includes literal double quotes then you'll need to If your intended value includes literal double quotes then you'll need to
escape those with a backslash: escape those with a backslash:
``` ```
terraform plan -var "name=va\"lue" opentf plan -var "name=va\"lue"
``` ```
PowerShell on Windows cannot correctly pass literal quotes to external programs, PowerShell on Windows cannot correctly pass literal quotes to external programs,
so we do not recommend using Terraform with PowerShell when you are on Windows. so we do not recommend using OpenTF with PowerShell when you are on Windows.
Use Windows Command Prompt instead. Use Windows Command Prompt instead.
The appropriate syntax for writing the variable value is different depending The appropriate syntax for writing the variable value is different depending
on the variable's [type constraint](/terraform/language/expressions/type-constraints). on the variable's [type constraint](/opentf/language/expressions/type-constraints).
The primitive types `string`, `number`, and `bool` all expect a direct string The primitive types `string`, `number`, and `bool` all expect a direct string
value with no special punctuation except that required by your shell, as value with no special punctuation except that required by your shell, as
shown in the above examples. For all other type constraints, including list, 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 map, and set types and the special `any` keyword, you must write a valid
Terraform language expression representing the value, and write any necessary OpenTF language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell quoting or escape characters to ensure it will pass through your shell
literally to Terraform. For example, for a `list(string)` type constraint: literally to OpenTF. For example, for a `list(string)` type constraint:
``` ```
# Unix-style shell # Unix-style shell
terraform plan -var 'name=["a", "b", "c"]' opentf plan -var 'name=["a", "b", "c"]'
# Windows Command Prompt (do not use PowerShell on Windows) # Windows Command Prompt (do not use PowerShell on Windows)
terraform plan -var "name=[\"a\", \"b\", \"c\"]" opentf plan -var "name=[\"a\", \"b\", \"c\"]"
``` ```
Similar constraints apply when setting input variables using environment Similar constraints apply when setting input variables using environment
variables. For more information on the various methods for setting root module variables. For more information on the various methods for setting root module
input variables, see input variables, see
[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables). [Assigning Values to Root Module Variables](/opentf/language/values/variables#assigning-values-to-root-module-variables).
### Resource Targeting ### Resource Targeting
> **Hands-on:** Try the [Target resources](/terraform/tutorials/state/resource-targeting?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. You can use the `-target` option to focus OpenTF's attention on only a
You can use the `-target` option to focus Terraform's attention on only a
subset of resources. subset of resources.
You can use [resource address syntax](/terraform/cli/state/resource-addressing) You can use [resource address syntax](/opentf/cli/state/resource-addressing)
to specify the constraint. Terraform interprets the resource address as follows: to specify the constraint. OpenTF interprets the resource address as follows:
* If the given address identifies one specific resource instance, Terraform * If the given address identifies one specific resource instance, OpenTF
will select that instance alone. For resources with either `count` or will select that instance alone. For resources with either `count` or
`for_each` set, a resource instance address must include the instance index `for_each` set, a resource instance address must include the instance index
part, like `aws_instance.example[0]`. part, like `aws_instance.example[0]`.
* If the given address identifies a resource as a whole, Terraform will select * 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` all of the instances of that resource. For resources with either `count`
or `for_each` set, this means selecting _all_ instance indexes currently or `for_each` set, this means selecting _all_ instance indexes currently
associated with that resource. For single-instance resources (without associated with that resource. For single-instance resources (without
either `count` or `for_each`), the resource address and the resource instance either `count` or `for_each`), the resource address and the resource instance
address are identical, so this possibility does not apply. address are identical, so this possibility does not apply.
* If the given address identifies an entire module instance, Terraform will * If the given address identifies an entire module instance, OpenTF will
select all instances of all resources that belong to that module instance select all instances of all resources that belong to that module instance
and all of its child module instances. and all of its child module instances.
Once Terraform has selected one or more resource instances that you've directly 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 targeted, it will also then extend the selection to include all other objects
that those selections depend on either directly or indirectly. that those selections depend on either directly or indirectly.
This targeting capability is provided for exceptional circumstances, such This targeting capability is provided for exceptional circumstances, such
as recovering from mistakes or working around Terraform limitations. It as recovering from mistakes or working around OpenTF limitations. It
is _not recommended_ to use `-target` for routine operations, since this can is _not recommended_ to use `-target` for routine operations, since this can
lead to undetected configuration drift and confusion about how the true state lead to undetected configuration drift and confusion about how the true state
of resources relates to configuration. of resources relates to configuration.
@ -263,17 +248,17 @@ of resources relates to configuration.
Instead of using `-target` as a means to operate on isolated portions of very Instead of using `-target` as a means to operate on isolated portions of very
large configurations, prefer instead to break large configurations into large configurations, prefer instead to break large configurations into
several smaller configurations that can each be independently applied. several smaller configurations that can each be independently applied.
[Data sources](/terraform/language/data-sources) can be used to access [Data sources](/opentf/language/data-sources) can be used to access
information about resources created in other configurations, allowing information about resources created in other configurations, allowing
a complex system architecture to be broken down into more manageable parts a complex system architecture to be broken down into more manageable parts
that can be updated independently. that can be updated independently.
## Other Options ## Other Options
The `terraform plan` command also has some other options that are related to 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 the input and output of the planning command, rather than customizing what
sort of plan Terraform will create. These commands are not necessarily also sort of plan OpenTF will create. These commands are not necessarily also
available on `terraform apply`, unless otherwise stated in the documentation available on `opentf apply`, unless otherwise stated in the documentation
for that command. for that command.
The available options are: The available options are:
@ -290,76 +275,64 @@ The available options are:
* 1 = Error * 1 = Error
* 2 = Succeeded with non-empty diff (changes present) * 2 = Succeeded with non-empty diff (changes present)
- `-generate-config-out=PATH` - (Experimental) If `import` blocks are present in configuration, instructs Terraform 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 Terraform will error. If the plan fails for another reason, Terraform may still attempt to write configuration. - `-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 Terraform's default behavior of prompting for * `-input=false` - Disables OpenTF's default behavior of prompting for
input for root module input variables that have not otherwise been assigned input for root module input variables that have not otherwise been assigned
a value. This option is particularly useful when running Terraform in a value. This option is particularly useful when running OpenTF in
non-interactive automation systems. non-interactive automation systems.
* `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output. * `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output.
This implies `-input=false`, so the configuration must have no unassigned This implies `-input=false`, so the configuration must have no unassigned
variable values to continue. variable values to continue.
[machine-readable-ui]: /terraform/internals/machine-readable-ui [machine-readable-ui]: /opentf/internals/machine-readable-ui
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
* `-no-color` - Disables terminal formatting sequences in the output. Use this * `-no-color` - Disables terminal formatting sequences in the output. Use this
if you are running Terraform in a context where its output will be if you are running OpenTF in a context where its output will be
rendered by a system that cannot interpret terminal formatting. rendered by a system that cannot interpret terminal formatting.
* `-out=FILENAME` - Writes the generated plan to the given filename in an * `-out=FILENAME` - Writes the generated plan to the given filename in an
opaque file format that you can later pass to `terraform apply` to execute opaque file format that you can later pass to `opentf apply` to execute
the planned changes, and to some other Terraform commands that can work with the planned changes, and to some other OpenTF commands that can work with
saved plan files. saved plan files.
Terraform will allow any filename for the plan file, but a typical 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 convention is to name it `tfplan`. **Do not** name the file with a suffix
that Terraform recognizes as another file format; if you use a `.tf` suffix that OpenTF recognizes as another file format; if you use a `.tf` suffix
then Terraform will try to interpret the file as a configuration source then OpenTF will try to interpret the file as a configuration source
file, which will then cause syntax errors for subsequent commands. file, which will then cause syntax errors for subsequent commands.
The generated file is not in any standard format intended for consumption The generated file is not in any standard format intended for consumption
by other software, but the file _does_ contain your full configuration, by other software, but the file _does_ contain your full configuration,
all of the values associated with planned changes, and all of the plan 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 options including the input variables. If your plan includes any sort of
sensitive data, even if obscured in Terraform's terminal output, it will 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 be saved in cleartext in the plan file. You should therefore treat any
saved plan files as potentially-sensitive artifacts. saved plan files as potentially-sensitive artifacts.
* `-parallelism=n` - Limit the number of concurrent operations as Terraform * `-parallelism=n` - Limit the number of concurrent operations as OpenTF
[walks the graph](/terraform/internals/graph#walking-the-graph). Defaults [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults
to 10. to 10.
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform plan` accepts the legacy command line option `opentf plan` accepts the legacy command line option
[`-state`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`](/opentf/language/settings/backends/local#command-line-arguments).
### Passing a Different Configuration Directory ### Passing a Different Configuration Directory
Terraform v0.13 and earlier accepted an additional positional argument giving
a directory path, in which case Terraform would use that directory as the root
module instead of the current working directory.
That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15.
If your workflow relies on overriding the root module directory, use If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) [the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look 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 in the given directory for all files it would normally read or write in the
current working directory. current working directory.
If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other
than the current working directory.

8
website/docs/cli/commands/providers.mdx
View File

@ -1,14 +1,14 @@
--- ---
page_title: 'Command: providers' page_title: 'Command: providers'
description: >- description: >-
The terraform providers command prints information about the providers The opentf providers command prints information about the providers
required in the current configuration. required in the current configuration.
--- ---
# Command: providers # Command: providers
The `terraform providers` command shows information about the The `opentf providers` command shows information about the
[provider requirements](/terraform/language/providers/requirements) of the [provider requirements](/opentf/language/providers/requirements) of the
configuration in the current working directory, as an aid to understanding configuration in the current working directory, as an aid to understanding
where each requirement was detected from. where each requirement was detected from.
@ -16,4 +16,4 @@ This command also has several subcommands with different purposes.
## Usage ## Usage
Usage: `terraform providers` Usage: `opentf providers`

72
website/docs/cli/commands/providers/lock.mdx
View File

@ -1,57 +1,55 @@
--- ---
page_title: 'Command: providers lock' page_title: 'Command: providers lock'
description: |- description: |-
The `terraform providers lock` command adds new provider selection information The `opentf providers lock` command adds new provider selection information
to the dependency lock file without initializing the referenced providers. to the dependency lock file without initializing the referenced providers.
--- ---
# Command: terraform providers lock # Command: opentf providers lock
The `terraform providers lock` consults upstream registries (by default) in The `opentf providers lock` consults upstream registries (by default) in
order to write provider dependency information into order to write provider dependency information into
[the dependency lock file](/terraform/language/files/dependency-lock). [the dependency lock file](/opentf/language/files/dependency-lock).
The common way to update the dependency lock file is as a side-effect of normal The common way to update the dependency lock file is as a side-effect of normal
provider installation during provider installation during
[`terraform init`](/terraform/cli/commands/init), but there are several situations where that [`opentf init`](/opentf/cli/commands/init), but there are several situations where that
automatic approach may not be sufficient: automatic approach may not be sufficient:
* If you are running Terraform in an environment that uses * If you are running OpenTF in an environment that uses
[alternative provider installation methods](/terraform/cli/config/config-file#provider-installation), [alternative provider installation methods](/opentf/cli/config/config-file#provider-installation),
such as filesystem or network mirrors, normal provider installation will not such as filesystem or network mirrors, normal provider installation will not
access the origin registry for a provider and therefore Terraform will not access the origin registry for a provider and therefore OpenTF will not
be able to populate all of the possible package checksums for the selected be able to populate all of the possible package checksums for the selected
provider versions. provider versions.
If you use `terraform lock` to write the official release checksums for a If you use `opentf lock` to write the official release checksums for a
provider into the dependency lock file then future `terraform init` runs provider into the dependency lock file then future `opentf init` runs
will verify the packages available in your selected mirror against the will verify the packages available in your selected mirror against the
official checksums previously recorded, giving additional certainty that official checksums previously recorded, giving additional certainty that
the mirror is serving the provider packages it is claiming to. the mirror is serving the provider packages it is claiming to.
* If your team runs Terraform across a number of different platforms (e.g. * If your team runs OpenTF across a number of different platforms (e.g.
on both Windows and Linux) and the upstream registry for a provider is unable on both Windows and Linux) and the upstream registry for a provider is unable
to provide signed checksums using the latest hashing scheme, subsequent runs to provide signed checksums using the latest hashing scheme, subsequent runs
of Terraform on other platforms may of OpenTF on other platforms may
[add additional checksums to the lock file](/terraform/language/files/dependency-lock#new-provider-package-checksums). [add additional checksums to the lock file](/opentf/language/files/dependency-lock#new-provider-package-checksums).
You can avoid that by pre-populating hashes for all of the platforms you You can avoid that by pre-populating hashes for all of the platforms you
intend to use, using the `terraform providers lock` command. intend to use, using the `opentf providers lock` command.
-> `terraform providers lock` is available only in Terraform v0.14 or later.
## Usage ## Usage
Usage: `terraform providers lock [options] [providers...]` Usage: `opentf providers lock [options] [providers...]`
With no additional command line arguments, `terraform providers lock` will With no additional command line arguments, `opentf providers lock` will
analyze the configuration in the current working directory to find all of analyze the configuration in the current working directory to find all of
the providers it depends on, and it will fetch the necessary data about those the providers it depends on, and it will fetch the necessary data about those
providers from their origin registries and then update providers from their origin registries and then update
[the dependency lock file](/terraform/language/files/dependency-lock) to [the dependency lock file](/opentf/language/files/dependency-lock) to
include a selected version for each provider and all of the package checksums include a selected version for each provider and all of the package checksums
that are covered by the provider developer's cryptographic signature. that are covered by the provider developer's cryptographic signature.
~> **Warning:** The `terraform providers lock` command prints information ~> **Warning:** The `opentf providers lock` command prints information
about what it has fetched and whether each package was signed using a about what it has fetched and whether each package was signed using a
cryptographic signature, but it cannot automatically verify that the cryptographic signature, but it cannot automatically verify that the
providers are trustworthy and that they comply with your local system providers are trustworthy and that they comply with your local system
@ -60,22 +58,22 @@ in the output to confirm that you trust all of the signers before committing
the updated lock file to your version control system. the updated lock file to your version control system.
If you list one or more provider source addresses on the command line then If you list one or more provider source addresses on the command line then
`terraform providers lock` will restrict its work only to those providers, `opentf providers lock` will restrict its work only to those providers,
leaving the lock entries for other providers (if any) unchanged. leaving the lock entries for other providers (if any) unchanged.
You can customize the default behavior using the following additional option: You can customize the default behavior using the following additional option:
* `-fs-mirror=PATH` - Direct Terraform to look for provider packages in the * `-fs-mirror=PATH` - Direct OpenTF to look for provider packages in the
given local filesystem mirror directory, instead of in upstream registries. given local filesystem mirror directory, instead of in upstream registries.
The given directory must use the usual filesystem mirror directory layout. The given directory must use the usual filesystem mirror directory layout.
* `-net-mirror=URL` - Direct Terraform to look for provider packages in the * `-net-mirror=URL` - Direct OpenTF to look for provider packages in the
given network mirror service, instead of in upstream registries. The given network mirror service, instead of in upstream registries. The
given URL must implement given URL must implement
[the Terraform provider network mirror protocol](/terraform/internals/provider-network-mirror-protocol). [the OpenTF provider network mirror protocol](/opentf/internals/provider-network-mirror-protocol).
* `-platform=OS_ARCH` - Specify a platform you intend to use to work with this * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this
Terraform configuration. Terraform will ensure that the providers are all OpenTF configuration. OpenTF will ensure that the providers are all
available for the given platform and will save enough package checksums in available for the given platform and will save enough package checksums in
the lock file to support _at least_ the specified platforms. the lock file to support _at least_ the specified platforms.
@ -91,16 +89,16 @@ You can customize the default behavior using the following additional option:
## Specifying Target Platforms ## Specifying Target Platforms
In your environment you may, for example, have both developers who work with In your environment you may, for example, have both developers who work with
your Terraform configuration on their Windows or macOS workstations _and_ your OpenTF configuration on their Windows or macOS workstations _and_
automated systems that apply the configuration while running on Linux. automated systems that apply the configuration while running on Linux.
In that situation, you could choose to verify that all of your providers support In that situation, you could choose to verify that all of your providers support
all of those platforms, and to pre-populate the lock file with the necessary all of those platforms, and to pre-populate the lock file with the necessary
checksums, by running `terraform providers lock` and specifying those three checksums, by running `opentf providers lock` and specifying those three
platforms: platforms:
``` ```
terraform providers lock \ opentf providers lock \
-platform=windows_amd64 \ # 64-bit Windows -platform=windows_amd64 \ # 64-bit Windows
-platform=darwin_amd64 \ # 64-bit macOS -platform=darwin_amd64 \ # 64-bit macOS
-platform=linux_amd64 # 64-bit Linux -platform=linux_amd64 # 64-bit Linux
@ -112,12 +110,12 @@ arguments on a single line, and remove the backslashes and comments.)
## Lock Entries for In-house Providers ## Lock Entries for In-house Providers
An _in-house provider_ is one that isn't published on a real Terraform provider An _in-house provider_ is one that isn't published on a real OpenTF provider
registry because it's developed and used only within a particular organization and registry because it's developed and used only within a particular organization and
distributed via either a filesystem mirror or network mirror. distributed via either a filesystem mirror or network mirror.
By default, `terraform providers lock` assumes all providers are available By default, `opentf providers lock` assumes all providers are available
at a Terraform provider registry and tries to contact the origin registries at a OpenTF provider registry and tries to contact the origin registries
in order to get access to the most detailed information about the provider in order to get access to the most detailed information about the provider
packages. packages.
@ -127,8 +125,8 @@ line options to override the default behavior of consulting the provider's
origin registry: origin registry:
``` ```
terraform providers lock \ opentf providers lock \
-fs-mirror=/usr/local/terraform/providers -fs-mirror=/usr/local/opentf/providers
-platform=windows_amd64 \ -platform=windows_amd64 \
-platform=darwin_amd64 \ -platform=darwin_amd64 \
-platform=linux_amd64 \ -platform=linux_amd64 \
@ -140,15 +138,15 @@ you are running the command on Windows then you will need to put all of the
arguments on a single line, and remove the backslashes.) arguments on a single line, and remove the backslashes.)
Because the command above includes the provider source address Because the command above includes the provider source address
`tf.example.com/ourcompany/ourplatform`, `terraform providers lock` will only `tf.example.com/ourcompany/ourplatform`, `opentf providers lock` will only
attempt to access that particular provider and will leave the lock entries attempt to access that particular provider and will leave the lock entries
for any other providers unchanged. If you have a variety of different providers for any other providers unchanged. If you have a variety of different providers
available from different sources, you can run `terraform providers lock` available from different sources, you can run `opentf providers lock`
multiple times and specify a different subset of your providers each time. multiple times and specify a different subset of your providers each time.
The `-fs-mirror` and `-net-mirror` options have the same meaning as The `-fs-mirror` and `-net-mirror` options have the same meaning as
`filesystem_mirror` and `network_mirror` blocks in `filesystem_mirror` and `network_mirror` blocks in
[the provider installation methods configuration](/terraform/cli/config/config-file#provider-installation), [the provider installation methods configuration](/opentf/cli/config/config-file#provider-installation),
but specify only a single method in order to be explicit about where you but specify only a single method in order to be explicit about where you
intend to derive the package checksum information from. intend to derive the package checksum information from.
@ -165,4 +163,4 @@ If you wish, you can publish your in-house providers via an in-house provider
registry, which will then allow locking and installation of those providers registry, which will then allow locking and installation of those providers
without any special options or additional CLI configuration. For more without any special options or additional CLI configuration. For more
information, see information, see
[the provider registry protocol](/terraform/internals/provider-registry-protocol). [the provider registry protocol](/opentf/internals/provider-registry-protocol).

34
website/docs/cli/commands/providers/mirror.mdx
View File

@ -1,53 +1,51 @@
--- ---
page_title: 'Command: providers mirror' page_title: 'Command: providers mirror'
description: |- description: |-
The `terraform providers mirror` command downloads the providers required The `opentf providers mirror` command downloads the providers required
for the current configuration and copies them into a directory in the local for the current configuration and copies them into a directory in the local
filesystem. filesystem.
--- ---
# Command: terraform providers mirror # Command: opentf providers mirror
The `terraform providers mirror` command downloads the providers required The `opentf providers mirror` command downloads the providers required
for the current configuration and copies them into a directory in the local for the current configuration and copies them into a directory in the local
filesystem. filesystem.
In normal use, `terraform init` will automatically download needed providers In normal use, `opentf init` will automatically download needed providers
from provider registries as part of initializing the current working directory. from provider registries as part of initializing the current working directory.
Sometimes Terraform is running in an environment where that isn't possible, Sometimes OpenTF is running in an environment where that isn't possible,
such as on an isolated network without access to the Terraform Registry. In such as on an isolated network without access to an OpenTF Registry. In
that case, that case,
[explicit installation method configuration](/terraform/cli/config/config-file#explicit-installation-method-configuration) [explicit installation method configuration](/opentf/cli/config/config-file#explicit-installation-method-configuration)
allows you to configure Terraform, when running on a particular system, to allows you to configure OpenTF, when running on a particular system, to
consult only a local filesystem directory where you've created a local mirror consult only a local filesystem directory where you've created a local mirror
of the necessary plugins, and to skip accessing the upstream registry at all. of the necessary plugins, and to skip accessing the upstream registry at all.
The `terraform providers mirror` command can automatically populate a directory The `opentf providers mirror` command can automatically populate a directory
that will be used as a local filesystem mirror in the provider installation that will be used as a local filesystem mirror in the provider installation
configuration. configuration.
-> `terraform providers mirror` is available only in Terraform v0.13 or later.
## Usage ## Usage
Usage: `terraform providers mirror [options] <target-dir>` Usage: `opentf providers mirror [options] <target-dir>`
A single target directory is required. Terraform will create under that A single target directory is required. OpenTF will create under that
directory the path structure that is expected for filesystem-based provider directory the path structure that is expected for filesystem-based provider
plugin mirrors, populating it with `.zip` files containing the plugins plugin mirrors, populating it with `.zip` files containing the plugins
themselves. themselves.
Terraform will also generate various `.json` index files which contain suitable OpenTF will also generate various `.json` index files which contain suitable
responses to implement responses to implement
[the network mirror protocol](/terraform/internals/provider-network-mirror-protocol), [the network mirror protocol](/opentf/internals/provider-network-mirror-protocol),
if you upload the resulting directory to a static website host. Terraform if you upload the resulting directory to a static website host. OpenTF
ignores those index files when using the directory as a filesystem mirror, ignores those index files when using the directory as a filesystem mirror,
because the directory entries themselves are authoritative in that case. because the directory entries themselves are authoritative in that case.
This command supports the following additional option: This command supports the following additional option:
* `-platform=OS_ARCH` - Choose which target platform to build a mirror for. * `-platform=OS_ARCH` - Choose which target platform to build a mirror for.
By default Terraform will obtain plugin packages suitable for the platform By default OpenTF will obtain plugin packages suitable for the platform
where you run this command. Use this flag multiple times to include packages where you run this command. Use this flag multiple times to include packages
for multiple target systems. for multiple target systems.
@ -55,7 +53,7 @@ This command supports the following additional option:
architecture. For example, `linux_amd64` selects the Linux operating system architecture. For example, `linux_amd64` selects the Linux operating system
running on an AMD64 or x86_64 CPU. running on an AMD64 or x86_64 CPU.
You can run `terraform providers mirror` again on an existing mirror directory You can run `opentf providers mirror` again on an existing mirror directory
to update it with new packages. For example, you can add packages for a new to update it with new packages. For example, you can add packages for a new
target platform by re-running the command with the desired new `-platform=...` target platform by re-running the command with the desired new `-platform=...`
option, and it will place the packages for that new platform without removing option, and it will place the packages for that new platform without removing

16
website/docs/cli/commands/providers/schema.mdx
View File

@ -1,21 +1,19 @@
--- ---
page_title: 'Command: providers schema' page_title: 'Command: providers schema'
description: >- description: >-
The `terraform providers schema` command prints detailed schemas for the The `opentf providers schema` command prints detailed schemas for the
providers used providers used
in the current configuration. in the current configuration.
--- ---
# Command: terraform providers schema # Command: opentf providers schema
The `terraform providers schema` command is used to print detailed schemas for the providers used in the current configuration. The `opentf providers schema` command is used to print detailed schemas for the providers used in the current configuration.
-> `terraform providers schema` requires **Terraform v0.12 or later**.
## Usage ## Usage
Usage: `terraform providers schema [options]` Usage: `opentf providers schema [options]`
The following flags are available: The following flags are available:
@ -23,7 +21,7 @@ The following flags are available:
Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options.
The output includes a `format_version` key, which as of Terraform 1.1.0 has The output includes a `format_version` key, which has
value `"1.0"`. The semantics of this version are: value `"1.0"`. The semantics of this version are:
- We will increment the minor version, e.g. `"1.1"`, for backward-compatible - We will increment the minor version, e.g. `"1.1"`, for backward-compatible
@ -34,7 +32,7 @@ value `"1.0"`. The semantics of this version are:
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). [the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises).
## Format Summary ## Format Summary
@ -44,7 +42,7 @@ To avoid excessive repetition, we've split the complete format into several disc
The JSON output format consists of the following objects and sub-objects: The JSON output format consists of the following objects and sub-objects:
- [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `terraform providers schema -json` - [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `opentf providers schema -json`
- [Schema Representation](#schema-representation) - a sub-object of providers, resources, and data sources that describes their schema - [Schema Representation](#schema-representation) - a sub-object of providers, resources, and data sources that describes their schema
- [Block Representation](#block-representation) - a sub-object of schemas that describes attributes and nested blocks - [Block Representation](#block-representation) - a sub-object of schemas that describes attributes and nested blocks

14
website/docs/cli/commands/push.mdx
View File

@ -1,14 +0,0 @@
---
page_title: 'Command: push'
description: >-
DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced
the old `terraform push` command.
---
# Command: push
!> **Important:** The `terraform push` command is no longer functional. We recommend the [Terraform Cloud CLI integration](/terraform/cli/cloud) instead, which allows you to run remote operations in Terraform Cloud directly from the command line.
The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise.
The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional.

37
website/docs/cli/commands/refresh.mdx
View File

@ -1,68 +1,59 @@
--- ---
page_title: 'Command: refresh' page_title: 'Command: refresh'
description: |- description: |-
The `terraform refresh` command reads the current settings from all managed The `opentf refresh` command reads the current settings from all managed
remote objects and updates the Terraform state to match. remote objects and updates the OpenTF state to match.
--- ---
# Command: refresh # Command: refresh
> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. The `opentf refresh` command reads the current settings from all managed
remote objects and updates the OpenTF state to match.
The `terraform refresh` command reads the current settings from all managed
remote objects and updates the Terraform state to match.
~> _Warning:_ This command is deprecated, because its default behavior is ~> _Warning:_ This command is deprecated, because its default behavior is
unsafe if you have misconfigured credentials for any of your providers. unsafe if you have misconfigured credentials for any of your providers.
See below for more information and recommended alternatives. See below for more information and recommended alternatives.
This won't modify your real remote objects, but it will modify the This won't modify your real remote objects, but it will modify the
[Terraform state](/terraform/language/state). [OpenTF state](/opentf/language/state).
You shouldn't typically need to use this command, because Terraform You shouldn't typically need to use this command, because OpenTF
automatically performs the same refreshing actions as a part of creating automatically performs the same refreshing actions as a part of creating
a plan in both the a plan in both the
[`terraform plan`](/terraform/cli/commands/plan) [`opentf plan`](/opentf/cli/commands/plan)
and and
[`terraform apply`](/terraform/cli/commands/apply) [`opentf apply`](/opentf/cli/commands/apply)
commands. This command is here primarily for backward compatibility, but commands. This command is here primarily for backward compatibility, but
we don't recommend using it because it provides no opportunity to review we don't recommend using it because it provides no opportunity to review
the effects of the operation before updating the state. the effects of the operation before updating the state.
## Usage ## Usage
Usage: `terraform refresh [options]` Usage: `opentf refresh [options]`
This command is effectively an alias for the following command: This command is effectively an alias for the following command:
``` ```
terraform apply -refresh-only -auto-approve opentf apply -refresh-only -auto-approve
``` ```
Consequently, it supports all of the same options as Consequently, it supports all of the same options as
[`terraform apply`](/terraform/cli/commands/apply) except that it does not accept a saved [`opentf apply`](/opentf/cli/commands/apply) except that it does not accept a saved
plan file, it doesn't allow selecting a planning mode other than "refresh only", plan file, it doesn't allow selecting a planning mode other than "refresh only",
and `-auto-approve` is always enabled. and `-auto-approve` is always enabled.
Automatically applying the effect of a refresh is risky. If you have Automatically applying the effect of a refresh is risky. If you have
misconfigured credentials for one or more providers, Terraform may misconfigured credentials for one or more providers, OpenTF may
be misled into thinking that all of the managed objects have been deleted, be misled into thinking that all of the managed objects have been deleted,
causing it to remove all of the tracked objects without any confirmation prompt. causing it to remove all of the tracked objects without any confirmation prompt.
Instead, we recommend using the following command in order to get the same Instead, we recommend using the following command in order to get the same
effect but with the opportunity to review the changes that Terraform has effect but with the opportunity to review the changes that OpenTF has
detected before committing them to the state: detected before committing them to the state:
``` ```
terraform apply -refresh-only opentf apply -refresh-only
``` ```
This alternative command will present an interactive prompt for you to confirm This alternative command will present an interactive prompt for you to confirm
the detected changes. the detected changes.
The `-refresh-only` option for `terraform plan` and `terraform apply` was
introduced in Terraform v0.15.4. For prior versions you must use
`terraform refresh` directly if you need this behavior, while taking into
account the warnings above. Wherever possible, avoid using `terraform refresh`
explicitly and instead rely on Terraform's behavior of automatically refreshing
existing objects as part of creating a normal plan.

30
website/docs/cli/commands/show.mdx
View File

@ -1,48 +1,48 @@
--- ---
page_title: 'Command: show' page_title: 'Command: show'
description: >- description: >-
The `terraform show` command is used to provide human-readable output from a The `opentf show` command is used to provide human-readable output from a
state or plan file. This can be used to inspect a plan to ensure that the state or plan file. This can be used to inspect a plan to ensure that the
planned operations are expected, or to inspect the current state as Terraform planned operations are expected, or to inspect the current state as OpenTF
sees it. sees it.
--- ---
# Command: show # Command: show
The `terraform show` command is used to provide human-readable output The `opentf show` command is used to provide human-readable output
from a state or plan file. This can be used to inspect a plan to ensure from a state or plan file. This can be used to inspect a plan to ensure
that the planned operations are expected, or to inspect the current state that the planned operations are expected, or to inspect the current state
as Terraform sees it. as OpenTF sees it.
Machine-readable output is generated by adding the `-json` command-line Machine-readable output is generated by adding the `-json` command-line
flag. flag.
-> **Note:** When using the `-json` command-line flag, any sensitive values in -> **Note:** When using the `-json` command-line flag, any sensitive values in
Terraform state will be displayed in plain text. For more information, see OpenTF state will be displayed in plain text. For more information, see
[Sensitive Data in State](/terraform/language/state/sensitive-data). [Sensitive Data in State](/opentf/language/state/sensitive-data).
## JSON Output ## JSON Output
For Terraform state files (including when no path is provided), For OpenTF state files (including when no path is provided),
`terraform show -json` will show a JSON representation of the state. `opentf show -json` will show a JSON representation of the state.
For Terraform plan files, `terraform show -json` will show a JSON representation For OpenTF plan files, `opentf show -json` will show a JSON representation
of the plan, configuration, and current state. of the plan, configuration, and current state.
If you've updated providers which contain new schema versions since the state If you've updated providers which contain new schema versions since the state
was written, the state needs to be upgraded before it can be displayed with was written, the state needs to be upgraded before it can be displayed with
`show -json`. If you are viewing a plan, it must be created without `show -json`. If you are viewing a plan, it must be created without
`-refresh=false`. If you are viewing a state file, run `terraform refresh` `-refresh=false`. If you are viewing a state file, run `opentf refresh`
first. first.
The output format is covered in detail in [JSON Output Format](/terraform/internals/json-format). The output format is covered in detail in [JSON Output Format](/opentf/internals/json-format).
## Usage ## Usage
Usage: `terraform show [options] [file]` Usage: `opentf show [options] [file]`
You may use `show` with a path to either a Terraform state file or plan You may use `show` with a path to either a OpenTF state file or plan
file. If you don't specify a file path, Terraform will show the latest state file. If you don't specify a file path, OpenTF will show the latest state
snapshot. snapshot.
This command accepts the following options: This command accepts the following options:
@ -50,5 +50,3 @@ This command accepts the following options:
* `-no-color` - Disables output with coloring * `-no-color` - Disables output with coloring
* `-json` - Displays machine-readable output from a state or plan file * `-json` - Displays machine-readable output from a state or plan file
-> JSON output via the `-json` option requires **Terraform v0.12 or later**.

22
website/docs/cli/commands/state/index.mdx
View File

@ -1,14 +1,14 @@
--- ---
page_title: 'Command: state' page_title: 'Command: state'
description: The `terraform state` command is used for advanced state management. description: The `opentf state` command is used for advanced state management.
--- ---
# State Command # State Command
The `terraform state` command is used for advanced state management. The `opentf state` command is used for advanced state management.
As your Terraform usage becomes more advanced, there are some cases where As your OpenTF usage becomes more advanced, there are some cases where
you may need to modify the [Terraform state](/terraform/language/state). you may need to modify the [OpenTF state](/opentf/language/state).
Rather than modify the state directly, the `terraform state` commands can Rather than modify the state directly, the `opentf state` commands can
be used in many cases instead. be used in many cases instead.
This command is a nested subcommand, meaning that it has further subcommands. This command is a nested subcommand, meaning that it has further subcommands.
@ -16,27 +16,27 @@ These subcommands are listed to the left.
## Usage ## Usage
Usage: `terraform state <subcommand> [options] [args]` Usage: `opentf state <subcommand> [options] [args]`
Please click a subcommand to the left for more information. Please click a subcommand to the left for more information.
## Remote State ## Remote State
The Terraform state subcommands all work with remote state just as if it The OpenTF state subcommands all work with remote state just as if it
was local state. Reads and writes may take longer than normal as each read was local state. Reads and writes may take longer than normal as each read
and each write do a full network roundtrip. Otherwise, backups are still and each write do a full network roundtrip. Otherwise, backups are still
written to disk and the CLI usage is the same as if it were local state. written to disk and the CLI usage is the same as if it were local state.
## Backups ## Backups
All `terraform state` subcommands that modify the state write backup All `opentf state` subcommands that modify the state write backup
files. The path of these backup file can be controlled with `-backup`. files. The path of these backup file can be controlled with `-backup`.
Subcommands that are read-only (such as [list](/terraform/cli/commands/state/list)) Subcommands that are read-only (such as [list](/opentf/cli/commands/state/list))
do not write any backup files since they aren't modifying the state. do not write any backup files since they aren't modifying the state.
Note that backups for state modification _can not be disabled_. Due to Note that backups for state modification _can not be disabled_. Due to
the sensitivity of the state file, Terraform forces every state modification the sensitivity of the state file, OpenTF forces every state modification
command to write a backup file. You'll have to remove these files manually command to write a backup file. You'll have to remove these files manually
if you don't want to keep them around. if you don't want to keep them around.
@ -46,5 +46,5 @@ The output and command-line structure of the state subcommands is
designed to be usable with Unix command-line tools such as grep, awk, designed to be usable with Unix command-line tools such as grep, awk,
and similar PowerShell commands. and similar PowerShell commands.
For advanced filtering and modification, we recommend piping Terraform For advanced filtering and modification, we recommend piping OpenTF
state subcommands together with other command line tools. state subcommands together with other command line tools.

22
website/docs/cli/commands/state/list.mdx
View File

@ -1,18 +1,18 @@
--- ---
page_title: 'Command: state list' page_title: 'Command: state list'
description: >- description: >-
The terraform state list command is used to list resources within a Terraform The opentf state list command is used to list resources within a OpenTF
state. state.
--- ---
# Command: state list # Command: state list
The `terraform state list` command is used to list resources within a The `opentf state list` command is used to list resources within a
[Terraform state](/terraform/language/state). [OpenTF state](/opentf/language/state).
## Usage ## Usage
Usage: `terraform state list [options] [address...]` Usage: `opentf state list [options] [address...]`
The command will list all resources in the state file matching the given The command will list all resources in the state file matching the given
addresses (if any). If no addresses are given, all resources are listed. addresses (if any). If no addresses are given, all resources are listed.
@ -24,12 +24,12 @@ within modules are listed last.
For complex infrastructures, the state can contain thousands of resources. For complex infrastructures, the state can contain thousands of resources.
To filter these, provide one or more patterns to the command. Patterns are To filter these, provide one or more patterns to the command. Patterns are
in [resource addressing format](/terraform/cli/state/resource-addressing). in [resource addressing format](/opentf/cli/state/resource-addressing).
The command-line flags are all optional. The following flags are available: The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
Ignored when [remote state](/terraform/language/state/remote) is used. Ignored when [remote state](/opentf/language/state/remote) is used.
* `-id=id` - ID of resources to show. Ignored when unset. * `-id=id` - ID of resources to show. Ignored when unset.
## Example: All Resources ## Example: All Resources
@ -37,7 +37,7 @@ The command-line flags are all optional. The following flags are available:
This example will list all resources, including modules: This example will list all resources, including modules:
``` ```
$ terraform state list $ opentf state list
aws_instance.foo aws_instance.foo
aws_instance.bar[0] aws_instance.bar[0]
aws_instance.bar[1] aws_instance.bar[1]
@ -49,7 +49,7 @@ module.elb.aws_elb.main
This example will only list resources for the given name: This example will only list resources for the given name:
``` ```
$ terraform state list aws_instance.bar $ opentf state list aws_instance.bar
aws_instance.bar[0] aws_instance.bar[0]
aws_instance.bar[1] aws_instance.bar[1]
``` ```
@ -59,7 +59,7 @@ aws_instance.bar[1]
This example will list resources in the given module and any submodules: This example will list resources in the given module and any submodules:
``` ```
$ terraform state list module.elb $ opentf state list module.elb
module.elb.aws_elb.main module.elb.aws_elb.main
module.elb.module.secgroups.aws_security_group.sg module.elb.module.secgroups.aws_security_group.sg
``` ```
@ -71,6 +71,6 @@ command line. This is useful to find where in your configuration a
specific resource is located. specific resource is located.
``` ```
$ terraform state list -id=sg-1234abcd $ opentf state list -id=sg-1234abcd
module.elb.aws_security_group.sg module.elb.aws_security_group.sg
``` ```

80
website/docs/cli/commands/state/mv.mdx
View File

@ -1,54 +1,54 @@
--- ---
page_title: 'Command: state mv' page_title: 'Command: state mv'
description: >- description: >-
The `terraform state mv` command changes bindings in Terraform state, The `opentf state mv` command changes bindings in OpenTF state,
associating existing remote objects with new resource instances. associating existing remote objects with new resource instances.
--- ---
# Command: state mv # Command: state mv
The main function of [Terraform state](/terraform/language/state) is The main function of [OpenTF state](/opentf/language/state) is
to track the bindings between resource instance addresses in your configuration to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally Terraform automatically and the remote objects they represent. Normally OpenTF automatically
updates the state in response to actions taken when applying a plan, such as updates the state in response to actions taken when applying a plan, such as
removing a binding for an remote object that has now been deleted. removing a binding for an remote object that has now been deleted.
You can use `terraform state mv` in the less common situation where you wish You can use `opentf state mv` in the less common situation where you wish
to retain an existing remote object but track it as a different resource to retain an existing remote object but track it as a different resource
instance address in Terraform, such as if you have renamed a resource block instance address in OpenTF, such as if you have renamed a resource block
or you have moved it into a different module in your configuration. or you have moved it into a different module in your configuration.
## Usage ## Usage
Usage: `terraform state mv [options] SOURCE DESTINATION` Usage: `opentf state mv [options] SOURCE DESTINATION`
Terraform will look in the current state for a resource instance, resource, OpenTF will look in the current state for a resource instance, resource,
or module that matches the given address, and if successful it will move the or module that matches the given address, and if successful it will move the
remote objects currently associated with the source to be tracked instead remote objects currently associated with the source to be tracked instead
by the destination. by the destination.
Both the source and destination addresses must use Both the source and destination addresses must use
[resource address syntax](/terraform/cli/state/resource-addressing), and [resource address syntax](/opentf/cli/state/resource-addressing), and
they must both refer to the same kind of object: you can only move a resource they must both refer to the same kind of object: you can only move a resource
instance to another resource instance, a whole module instance to another instance to another resource instance, a whole module instance to another
whole module instance, etc. Furthermore, if you are moving a resource or whole module instance, etc. Furthermore, if you are moving a resource or
a resource instance then you can only move it to a new address with the a resource instance then you can only move it to a new address with the
same resource type. same resource type.
The most common uses for `terraform state mv` are when you have renamed a The most common uses for `opentf state mv` are when you have renamed a
resource block in your configuration or you've moved a resource block into resource block in your configuration or you've moved a resource block into
a child module, in both cases with the intention of retaining the existing a child module, in both cases with the intention of retaining the existing
object but tracking it under a new name. By default Terraform will understand object but tracking it under a new name. By default OpenTF will understand
moving or renaming a resource configuration as a request to delete the old moving or renaming a resource configuration as a request to delete the old
object and create a new object at the new address, and so `terraform state mv` object and create a new object at the new address, and so `opentf state mv`
allows you to override that interpretation by pre-emptively attaching the allows you to override that interpretation by pre-emptively attaching the
existing object to the new address in Terraform. existing object to the new address in OpenTF.
~> _Warning:_ If you are using Terraform in a collaborative environment, you ~> _Warning:_ If you are using OpenTF in a collaborative environment, you
must ensure that when you are using `terraform state mv` for a code refactoring must ensure that when you are using `opentf state mv` for a code refactoring
purpose you communicate carefully with your coworkers to ensure that nobody purpose you communicate carefully with your coworkers to ensure that nobody
makes any other changes between your configuration change and your makes any other changes between your configuration change and your
`terraform state mv` command, because otherwise they might inadvertently create `opentf state mv` command, because otherwise they might inadvertently create
a plan that will destroy the old object and create a new object at the new a plan that will destroy the old object and create a new object at the new
address. address.
@ -62,26 +62,26 @@ This command also accepts the following options:
workspace. workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform state mv` only, `opentf state mv`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
The legacy options [`-backup` and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments) The legacy options [`-backup` and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments)
operate on a local state file only. Configurations using operate on a local state file only. Configurations using
[the `remote` backend](/terraform/language/settings/backends/remote) [the `remote` backend](/opentf/language/settings/backends/remote)
must specify a local state file with the [`-state`](/terraform/language/settings/backends/local#command-line-arguments) must specify a local state file with the [`-state`](/opentf/language/settings/backends/local#command-line-arguments)
option in order to use the [`-backup` and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments) option in order to use the [`-backup` and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments)
options. options.
For configurations using For configurations using
[the `local` state mv](/terraform/language/settings/backends/local) only, [the `local` state mv](/opentf/language/settings/backends/local) only,
`terraform state mv` also accepts the legacy options `opentf state mv` also accepts the legacy options
[`-state`, `-state-out`, `-backup`, and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, `-backup`, and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments).
## Example: Rename a Resource ## Example: Rename a Resource
@ -94,12 +94,12 @@ Renaming a resource means making a configuration change like the following:
} }
``` ```
To tell Terraform that it should treat the new "helper" resource as a rename To tell OpenTF that it should treat the new "helper" resource as a rename
of the old "worker" resource, you can pair the above configuration change of the old "worker" resource, you can pair the above configuration change
with the following command: with the following command:
```shell ```shell
terraform state mv packet_device.worker packet_device.helper opentf state mv packet_device.worker packet_device.helper
``` ```
## Example: Move a Resource Into a Module ## Example: Move a Resource Into a Module
@ -107,10 +107,10 @@ terraform state mv packet_device.worker packet_device.helper
If you originally wrote a resource in your root module but now wish to refactor If you originally wrote a resource in your root module but now wish to refactor
it into a child module, you can move the `resource` block into the child it into a child module, you can move the `resource` block into the child
module configuration, removing the original in the root module, and then module configuration, removing the original in the root module, and then
run the following command to tell Terraform to treat it as a move: run the following command to tell OpenTF to treat it as a move:
```shell ```shell
terraform state mv packet_device.worker module.worker.packet_device.worker opentf state mv packet_device.worker module.worker.packet_device.worker
``` ```
In the above example the new resource has the same name but a different module In the above example the new resource has the same name but a different module
@ -118,7 +118,7 @@ address. You could also change the resource name at the same time, if the new
module organization suggests a different naming scheme: module organization suggests a different naming scheme:
```shell ```shell
terraform state mv packet_device.worker module.worker.packet_device.main opentf state mv packet_device.worker module.worker.packet_device.main
``` ```
## Example: Move a Module Into a Module ## Example: Move a Module Into a Module
@ -128,18 +128,18 @@ configuration, move the `module` block representing the module into a different
module and then pair that change with a command like the following: module and then pair that change with a command like the following:
```shell ```shell
terraform state mv module.app module.parent.module.app opentf state mv module.app module.parent.module.app
``` ```
## Example: Move a Particular Instance of a Resource using `count` ## Example: Move a Particular Instance of a Resource using `count`
A resource defined with [the `count` meta-argument](/terraform/language/meta-arguments/count) A resource defined with [the `count` meta-argument](/opentf/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given select a particular instance by including an explicit index in your given
address: address:
```shell ```shell
$ terraform state mv 'packet_device.worker[0]' 'packet_device.helper[0]' $ opentf state mv 'packet_device.worker[0]' 'packet_device.helper[0]'
``` ```
A resource that doesn't use `count` or `for_each` has only a single resource A resource that doesn't use `count` or `for_each` has only a single resource
@ -149,16 +149,16 @@ or the opposite, as long as the address type you use matches whether and how
each resource is configured: each resource is configured:
```shell ```shell
$ terraform state mv 'packet_device.main' 'packet_device.all[0]' $ opentf state mv 'packet_device.main' 'packet_device.all[0]'
``` ```
Brackets (`[`, `]`) have a special meaning in some shells, so you may need to Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
quote or escape the address in order to pass it literally to Terraform. quote or escape the address in order to pass it literally to OpenTF.
The above examples show the typical quoting syntax for Unix-style shells. The above examples show the typical quoting syntax for Unix-style shells.
## Example: Move a Resource configured with for_each ## Example: Move a Resource configured with for_each
A resource defined with [the `for_each` meta-argument](/terraform/language/meta-arguments/for_each) A resource defined with [the `for_each` meta-argument](/opentf/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can has multiple instances that are each identified by an string. You can
select a particular instance by including an explicit key in your given select a particular instance by including an explicit key in your given
address. address.
@ -170,19 +170,19 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS: Unix-style shells, such as on Linux or macOS:
```shell ```shell
terraform state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]' opentf state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
``` ```
Windows Command Prompt (`cmd.exe`): Windows Command Prompt (`cmd.exe`):
```shell ```shell
terraform state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"] opentf state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
``` ```
PowerShell: PowerShell:
```shell ```shell
terraform state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]' opentf state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
``` ```
Aside from the use of strings instead of integers for instance keys, the Aside from the use of strings instead of integers for instance keys, the

16
website/docs/cli/commands/state/pull.mdx
View File

@ -1,30 +1,30 @@
--- ---
page_title: 'Command: state pull' page_title: 'Command: state pull'
description: >- description: >-
The `terraform state pull` command is used to manually download and output the The `opentf state pull` command is used to manually download and output the
state from remote state. state from remote state.
--- ---
# Command: state pull # Command: state pull
The `terraform state pull` command is used to manually download and output The `opentf state pull` command is used to manually download and output
the state from [remote state](/terraform/language/state/remote). This command also the state from [remote state](/opentf/language/state/remote). This command also
works with local state. works with local state.
## Usage ## Usage
Usage: `terraform state pull` Usage: `opentf state pull`
This command downloads the state from its current location, upgrades the This command downloads the state from its current location, upgrades the
local copy to the latest state file version that is compatible with local copy to the latest state file version that is compatible with
locally-installed Terraform, and outputs the raw format to stdout. locally-installed OpenTF, and outputs the raw format to stdout.
This is useful for reading values out of state (potentially pairing this This is useful for reading values out of state (potentially pairing this
command with something like [jq](https://stedolan.github.io/jq/)). It is command with something like [jq](https://stedolan.github.io/jq/)). It is
also useful if you need to make manual modifications to state. also useful if you need to make manual modifications to state.
You cannot use this command to inspect the Terraform version of You cannot use this command to inspect the OpenTF version of
the remote state, as it will always be converted to the current Terraform the remote state, as it will always be converted to the current OpenTF
version before output. version before output.
-> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state pull | sc terraform.tfstate`. -> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state pull | sc opentf.tfstate`.

24
website/docs/cli/commands/state/push.mdx
View File

@ -1,12 +1,12 @@
--- ---
page_title: 'Command: state push' page_title: 'Command: state push'
description: The `terraform state push` command pushes items to the Terraform state. description: The `opentf state push` command pushes items to the OpenTF state.
--- ---
# Command: state push # Command: state push
The `terraform state push` command is used to manually upload a local The `opentf state push` command is used to manually upload a local
state file to [remote state](/terraform/language/state/remote). This command also state file to [remote state](/opentf/language/state/remote). This command also
works with local state. works with local state.
This command should rarely be used. It is meant only as a utility in case This command should rarely be used. It is meant only as a utility in case
@ -14,27 +14,27 @@ manual intervention is necessary with the remote state.
## Usage ## Usage
Usage: `terraform state push [options] PATH` Usage: `opentf state push [options] PATH`
This command pushes the state specified by PATH to the currently This command pushes the state specified by PATH to the currently
configured [backend](/terraform/language/settings/backends/configuration). configured [backend](/opentf/language/settings/backends/configuration).
If PATH is "-" then the state data to push is read from stdin. This data If PATH is "-" then the state data to push is read from stdin. This data
is loaded completely into memory and verified prior to being written to is loaded completely into memory and verified prior to being written to
the destination state. the destination state.
-> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state push | sc terraform.tfstate`. -> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state push | sc opentf.tfstate`.
Terraform will perform a number of safety checks to prevent you from OpenTF will perform a number of safety checks to prevent you from
making changes that appear to be unsafe: making changes that appear to be unsafe:
- **Differing lineage**: If the "lineage" value in the state differs, - **Differing lineage**: If the "lineage" value in the state differs,
Terraform will not allow you to push the state. A differing lineage OpenTF will not allow you to push the state. A differing lineage
suggests that the states are completely different and you may lose suggests that the states are completely different and you may lose
data. data.
- **Higher remote serial**: If the "serial" value in the destination state - **Higher remote serial**: If the "serial" value in the destination state
is higher than the state being pushed, Terraform will prevent the push. is higher than the state being pushed, OpenTF will prevent the push.
A higher serial suggests that data is in the destination state that isn't A higher serial suggests that data is in the destination state that isn't
accounted for in the local state being pushed. accounted for in the local state being pushed.
@ -42,7 +42,7 @@ Both of these safety checks can be disabled with the `-force` flag.
**This is not recommended.** If you disable the safety checks and are **This is not recommended.** If you disable the safety checks and are
pushing state, the destination state will be overwritten. pushing state, the destination state will be overwritten.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform state push` only, `opentf state push`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).

24
website/docs/cli/commands/state/replace-provider.mdx
View File

@ -1,18 +1,18 @@
--- ---
page_title: 'Command: state replace-provider' page_title: 'Command: state replace-provider'
description: >- description: >-
The `terraform state replace-provider` command replaces the provider for The `opentf state replace-provider` command replaces the provider for
resources in the Terraform state. resources in the OpenTF state.
--- ---
# Command: state replace-provider # Command: state replace-provider
The `terraform state replace-provider` command is used to replace the provider The `opentf state replace-provider` command is used to replace the provider
for resources in a [Terraform state](/terraform/language/state). for resources in a [OpenTF state](/opentf/language/state).
## Usage ## Usage
Usage: `terraform state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN` Usage: `opentf state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN`
This command will update all resources using the "from" provider, setting the This command will update all resources using the "from" provider, setting the
provider to the specified "to" provider. This allows changing the source of a provider to the specified "to" provider. This allows changing the source of a
@ -32,20 +32,20 @@ This command also accepts the following options:
- `-lock-timeout=0s` - Duration to retry a state lock. - `-lock-timeout=0s` - Duration to retry a state lock.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform state replace-provider` only, `opentf state replace-provider`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using For configurations using
[the `local` state](/terraform/language/settings/backends/local) only, [the `local` state](/opentf/language/settings/backends/local) only,
`terraform state replace-provider` also accepts the legacy options `opentf state replace-provider` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).
## Example ## Example
The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`: The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`:
```shell ```shell
$ terraform state replace-provider hashicorp/aws registry.acme.corp/acme/aws $ opentf state replace-provider hashicorp/aws registry.acme.corp/acme/aws
``` ```

60
website/docs/cli/commands/state/rm.mdx
View File

@ -1,35 +1,35 @@
--- ---
page_title: 'Command: state rm' page_title: 'Command: state rm'
description: >- description: >-
The `terraform state rm` command removes bindings from the Terraform state, The `opentf state rm` command removes bindings from the OpenTF state,
causing Terraform to "forget about" existing objects. causing OpenTF to "forget about" existing objects.
--- ---
# Command: state rm # Command: state rm
The main function of [Terraform state](/terraform/language/state) is The main function of [OpenTF state](/opentf/language/state) is
to track the bindings between resource instance addresses in your configuration to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally Terraform automatically and the remote objects they represent. Normally OpenTF automatically
updates the state in response to actions taken when applying a plan, such as updates the state in response to actions taken when applying a plan, such as
removing a binding for a remote object that has now been deleted. removing a binding for a remote object that has now been deleted.
You can use `terraform state rm` in the less common situation where you wish You can use `opentf state rm` in the less common situation where you wish
to remove a binding to an existing remote object without first destroying it, to remove a binding to an existing remote object without first destroying it,
which will effectively make Terraform "forget" the object while it continues which will effectively make OpenTF "forget" the object while it continues
to exist in the remote system. to exist in the remote system.
## Usage ## Usage
Usage: `terraform state rm [options] ADDRESS...` Usage: `opentf state rm [options] ADDRESS...`
Terraform will search the state for any instances matching the given OpenTF will search the state for any instances matching the given
[resource address](/terraform/cli/state/resource-addressing), and remove [resource address](/opentf/cli/state/resource-addressing), and remove
the record of each one so that Terraform will no longer be tracking the the record of each one so that OpenTF will no longer be tracking the
corresponding remote objects. corresponding remote objects.
This means that although the objects will still continue to exist in the This means that although the objects will still continue to exist in the
remote system, a subsequent remote system, a subsequent
[`terraform plan`](/terraform/cli/commands/plan) [`opentf plan`](/opentf/cli/commands/plan)
will include an action to create a new object for each of the "forgotten" will include an action to create a new object for each of the "forgotten"
instances. Depending on the constraints imposed by the remote system, creating instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with those objects might fail if their names or other identifiers conflict with
@ -45,27 +45,27 @@ This command also accepts the following options:
workspace. workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform state rm` only, `opentf state rm`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using For configurations using
[the `local` state rm](/terraform/language/settings/backends/local) only, [the `local` state rm](/opentf/language/settings/backends/local) only,
`terraform state rm` also accepts the legacy options `opentf state rm` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).
## Example: Remove all Instances of a Resource ## Example: Remove all Instances of a Resource
The following example will cause Terraform to "forget" all of the instances The following example will cause OpenTF to "forget" all of the instances
of the `packet_device` resource named "worker". of the `packet_device` resource named "worker".
```shell ```shell
$ terraform state rm 'packet_device.worker' $ opentf state rm 'packet_device.worker'
``` ```
A resource that doesn't use `count` or `for_each` has only one instance, so A resource that doesn't use `count` or `for_each` has only one instance, so
@ -77,37 +77,37 @@ To select a resource that you've defined in a child module you must specify
the path of that module as part of the resource address: the path of that module as part of the resource address:
```shell ```shell
$ terraform state rm 'module.foo.packet_device.worker' $ opentf state rm 'module.foo.packet_device.worker'
``` ```
## Example: Remove all Instances of all Resources in a Module ## Example: Remove all Instances of all Resources in a Module
The following example will cause Terraform to "forget" all of the instances The following example will cause OpenTF to "forget" all of the instances
associated with all resources defined in all instances of the module named associated with all resources defined in all instances of the module named
`foo`: `foo`:
```shell ```shell
$ terraform state rm 'module.foo' $ opentf state rm 'module.foo'
``` ```
## Example: Remove a Particular Instance of a Resource using `count` ## Example: Remove a Particular Instance of a Resource using `count`
A resource defined with [the `count` meta-argument](/terraform/language/meta-arguments/count) A resource defined with [the `count` meta-argument](/opentf/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given select a particular instance by including an explicit index in your given
address: address:
```shell ```shell
$ terraform state rm 'packet_device.worker[0]' $ opentf state rm 'packet_device.worker[0]'
``` ```
Brackets (`[`, `]`) have a special meaning in some shells, so you may need to Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
quote or escape the address in order to pass it literally to Terraform. quote or escape the address in order to pass it literally to OpenTF.
The above shows the typical quoting syntax for Unix-style shells. The above shows the typical quoting syntax for Unix-style shells.
## Example: Remove a Particular Instance of a Resource using `for_each` ## Example: Remove a Particular Instance of a Resource using `for_each`
A resource defined with [the `for_each` meta-argument](/terraform/language/meta-arguments/for_each) A resource defined with [the `for_each` meta-argument](/opentf/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can has multiple instances that are each identified by an string. You can
select a particular instance by including an explicit key in your given select a particular instance by including an explicit key in your given
address. address.
@ -119,17 +119,17 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS: Unix-style shells, such as on Linux or macOS:
```shell ```shell
$ terraform state rm 'packet_device.worker["example"]' $ opentf state rm 'packet_device.worker["example"]'
``` ```
Windows Command Prompt (`cmd.exe`): Windows Command Prompt (`cmd.exe`):
```shell ```shell
$ terraform state rm packet_device.worker[\"example\"] $ opentf state rm packet_device.worker[\"example\"]
``` ```
PowerShell: PowerShell:
```shell ```shell
$ terraform state rm 'packet_device.worker[\"example\"]' $ opentf state rm 'packet_device.worker[\"example\"]'
``` ```

36
website/docs/cli/commands/state/show.mdx
View File

@ -1,35 +1,35 @@
--- ---
page_title: 'Command: state show' page_title: 'Command: state show'
description: >- description: >-
The `terraform state show` command is used to show the attributes of a single The `opentf state show` command is used to show the attributes of a single
resource in the Terraform state. resource in the OpenTF state.
--- ---
# Command: state show # Command: state show
The `terraform state show` command is used to show the attributes of a The `opentf state show` command is used to show the attributes of a
single resource in the single resource in the
[Terraform state](/terraform/language/state). [OpenTF state](/opentf/language/state).
## Usage ## Usage
Usage: `terraform state show [options] ADDRESS` Usage: `opentf state show [options] ADDRESS`
The command will show the attributes of a single resource in the The command will show the attributes of a single resource in the
state file that matches the given address. state file that matches the given address.
This command requires an address that points to a single resource in the This command requires an address that points to a single resource in the
state. Addresses are state. Addresses are
in [resource addressing format](/terraform/cli/state/resource-addressing). in [resource addressing format](/opentf/cli/state/resource-addressing).
The command-line flags are all optional. The following flags are available: The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
Ignored when [remote state](/terraform/language/state/remote) is used. Ignored when [remote state](/opentf/language/state/remote) is used.
The output of `terraform state show` is intended for human consumption, not The output of `opentf state show` is intended for human consumption, not
programmatic consumption. To extract state data for use in other software, use programmatic consumption. To extract state data for use in other software, use
[`terraform show -json`](/terraform/cli/commands/show#json-output) and decode the result [`opentf show -json`](/opentf/cli/commands/show#json-output) and decode the result
using the documented structure. using the documented structure.
## Example: Show a Resource ## Example: Show a Resource
@ -37,7 +37,7 @@ using the documented structure.
The example below shows a `packet_device` resource named `worker`: The example below shows a `packet_device` resource named `worker`:
``` ```
$ terraform state show 'packet_device.worker' $ opentf state show 'packet_device.worker'
# packet_device.worker: # packet_device.worker:
resource "packet_device" "worker" { resource "packet_device" "worker" {
billing_cycle = "hourly" billing_cycle = "hourly"
@ -54,36 +54,36 @@ resource "packet_device" "worker" {
The example below shows a `packet_device` resource named `worker` inside a module named `foo`: The example below shows a `packet_device` resource named `worker` inside a module named `foo`:
```shell ```shell
$ terraform state show 'module.foo.packet_device.worker' $ opentf state show 'module.foo.packet_device.worker'
``` ```
## Example: Show a Resource configured with count ## Example: Show a Resource configured with count
The example below shows the first instance of a `packet_device` resource named `worker` configured with The example below shows the first instance of a `packet_device` resource named `worker` configured with
[`count`](/terraform/language/meta-arguments/count): [`count`](/opentf/language/meta-arguments/count):
```shell ```shell
$ terraform state show 'packet_device.worker[0]' $ opentf state show 'packet_device.worker[0]'
``` ```
## Example: Show a Resource configured with for_each ## Example: Show a Resource configured with for_each
The following example shows the `"example"` instance of a `packet_device` resource named `worker` configured with the [`for_each`](/terraform/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes. The following example shows the `"example"` instance of a `packet_device` resource named `worker` configured with the [`for_each`](/opentf/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes.
Linux, Mac OS, and UNIX: Linux, Mac OS, and UNIX:
```shell ```shell
$ terraform state show 'packet_device.worker["example"]' $ opentf state show 'packet_device.worker["example"]'
``` ```
PowerShell: PowerShell:
```shell ```shell
$ terraform state show 'packet_device.worker[\"example\"]' $ opentf state show 'packet_device.worker[\"example\"]'
``` ```
Windows `cmd.exe`: Windows `cmd.exe`:
```shell ```shell
$ terraform state show packet_device.worker[\"example\"] $ opentf state show packet_device.worker[\"example\"]
``` ```

34
website/docs/cli/commands/taint.mdx
View File

@ -1,38 +1,38 @@
--- ---
page_title: 'Command: taint' page_title: 'Command: taint'
description: |- description: |-
The `terraform taint` command informs Terraform that a particular object The `opentf taint` command informs OpenTF that a particular object
is damaged or degraded. is damaged or degraded.
--- ---
# Command: taint # Command: taint
The `terraform taint` command informs Terraform that a particular object has The `opentf taint` command informs OpenTF that a particular object has
become degraded or damaged. Terraform represents this by marking the become degraded or damaged. OpenTF represents this by marking the
object as "tainted" in the Terraform state, and Terraform will object as "tainted" in the OpenTF state, and OpenTF will
propose to replace it in the next plan you create. propose to replace it in the next plan you create.
~> **Warning:** This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below). ~> **Warning:** This command is deprecated, we recommend using the `-replace` option with `opentf apply` instead (details below).
## Recommended Alternative ## Recommended Alternative
For Terraform v0.15.2 and later, we recommend using the [`-replace` option](/terraform/cli/commands/plan#replace-address) with `terraform apply` to force Terraform to replace an object even though there are no configuration changes that would require it. We recommend using the [`-replace` option](/opentf/cli/commands/plan#replace-address) with `opentf apply` to force OpenTF to replace an object even though there are no configuration changes that would require it.
``` ```
$ terraform apply -replace="aws_instance.example[0]" $ opentf apply -replace="aws_instance.example[0]"
``` ```
We recommend the `-replace` option because the change will be reflected in the Terraform plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `terraform taint`, other users could create a new plan against your tainted object before you can review the effects. We recommend the `-replace` option because the change will be reflected in the OpenTF plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `opentf taint`, other users could create a new plan against your tainted object before you can review the effects.
## Usage ## Usage
``` ```
$ terraform taint [options] <address> $ opentf taint [options] <address>
``` ```
The `address` argument is the address of the resource to mark as tainted. The `address` argument is the address of the resource to mark as tainted.
The address is in The address is in
[the resource address syntax](/terraform/cli/state/resource-addressing), [the resource address syntax](/opentf/cli/state/resource-addressing),
as shown in the output from other commands, such as: as shown in the output from other commands, such as:
- `aws_instance.foo` - `aws_instance.foo`
@ -47,19 +47,19 @@ This command accepts the following options:
for other situations, such as if there is a problem reading or writing for other situations, such as if there is a problem reading or writing
the state. the state.
- `-lock=false` - Disables Terraform's default behavior of attempting to take - `-lock=false` - Disables OpenTF's default behavior of attempting to take
a read/write lock on the state for the duration of the operation. a read/write lock on the state for the duration of the operation.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) only, `terraform taint` For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) only, `opentf taint`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform taint` also accepts the legacy options `opentf taint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).

4
website/docs/cli/commands/test.mdx
View File

@ -5,8 +5,8 @@ description: Part of the ongoing design research for module integration testing.
# Command: test # Command: test
The `terraform test` command is currently serving as part of The `opentf test` command is currently serving as part of
[the module integration testing experiment](/terraform/language/modules/testing-experiment). [the module integration testing experiment](/opentf/language/modules/testing-experiment).
It's not ready for routine use, but if you'd be interested in trying the It's not ready for routine use, but if you'd be interested in trying the
prototype functionality then we'd love to hear your feedback. See the prototype functionality then we'd love to hear your feedback. See the

38
website/docs/cli/commands/untaint.mdx
View File

@ -1,27 +1,27 @@
--- ---
page_title: 'Command: untaint' page_title: 'Command: untaint'
description: |- description: |-
The `terraform untaint` command tells Terraform that an object is functioning The `opentf untaint` command tells OpenTF that an object is functioning
correctly, even though its creation failed or it was previously manually correctly, even though its creation failed or it was previously manually
marked as degraded. marked as degraded.
--- ---
# Command: untaint # Command: untaint
Terraform has a marker called "tainted" which it uses to track that an object OpenTF has a marker called "tainted" which it uses to track that an object
might be damaged and so a future Terraform plan ought to replace it. might be damaged and so a future OpenTF plan ought to replace it.
Terraform automatically marks an object as "tainted" if an error occurs during OpenTF automatically marks an object as "tainted" if an error occurs during
a multi-step "create" action, because Terraform can't be sure that the object a multi-step "create" action, because OpenTF can't be sure that the object
was left in a fully-functional state. was left in a fully-functional state.
You can also manually mark an object as "tainted" using the deprecated command You can also manually mark an object as "tainted" using the deprecated command
[`terraform taint`](/terraform/cli/commands/taint), although we no longer recommend that [`opentf taint`](/opentf/cli/commands/taint), although we no longer recommend that
workflow. workflow.
If Terraform currently considers a particular object as tainted but you've If OpenTF currently considers a particular object as tainted but you've
determined that it's actually functioning correctly and need _not_ be replaced, determined that it's actually functioning correctly and need _not_ be replaced,
you can use `terraform untaint` to remove the taint marker from that object. you can use `opentf untaint` to remove the taint marker from that object.
This command _will not_ modify any real remote objects, but will modify the This command _will not_ modify any real remote objects, but will modify the
state in order to remove the tainted status. state in order to remove the tainted status.
@ -31,14 +31,14 @@ was degraded after all, you can create and apply a plan to replace it without
first re-tainting the object, by using a command like the following: first re-tainting the object, by using a command like the following:
``` ```
terraform apply -replace="aws_instance.example[0]" opentf apply -replace="aws_instance.example[0]"
``` ```
## Usage ## Usage
Usage: `terraform untaint [options] address` Usage: `opentf untaint [options] address`
The `address` argument is a [resource address](/terraform/cli/state/resource-addressing) The `address` argument is a [resource address](/opentf/cli/state/resource-addressing)
identifying a particular resource instance which is currently tainted. identifying a particular resource instance which is currently tainted.
This command also accepts the following options: This command also accepts the following options:
@ -53,20 +53,20 @@ This command also accepts the following options:
workspace. workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before 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 returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
- `-no-color` - Disables terminal formatting sequences in the output. Use this - `-no-color` - Disables terminal formatting sequences in the output. Use this
if you are running Terraform in a context where its output will be if you are running OpenTF in a context where its output will be
rendered by a system that cannot interpret terminal formatting. rendered by a system that cannot interpret terminal formatting.
For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote)
only, `terraform untaint` only, `opentf untaint`
also accepts the option also accepts the option
[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). [`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using For configurations using
[the `local` backend](/terraform/language/settings/backends/local) only, [the `local` backend](/opentf/language/settings/backends/local) only,
`terraform untaint` also accepts the legacy options `opentf untaint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments).

46
website/docs/cli/commands/validate.mdx
View File

@ -1,13 +1,13 @@
--- ---
page_title: 'Command: validate' page_title: 'Command: validate'
description: >- description: >-
The `terraform validate` command is used to validate the syntax of the The `opentf validate` command is used to validate the syntax of the
terraform files. opentf files.
--- ---
# Command: validate # Command: validate
The `terraform validate` command validates the configuration files in a The `opentf validate` command validates the configuration files in a
directory, referring only to the configuration and not accessing any remote directory, referring only to the configuration and not accessing any remote
services such as remote state, provider APIs, etc. services such as remote state, provider APIs, etc.
@ -23,16 +23,16 @@ system.
Validation requires an initialized working directory with any referenced plugins and modules installed. To initialize a working directory for validation without accessing any configured backend, use: Validation requires an initialized working directory with any referenced plugins and modules installed. To initialize a working directory for validation without accessing any configured backend, use:
``` ```
$ terraform init -backend=false $ opentf init -backend=false
``` ```
To verify configuration in the context of a particular run (a particular To verify configuration in the context of a particular run (a particular
target workspace, input variable values, etc), use the `terraform plan` target workspace, input variable values, etc), use the `opentf plan`
command instead, which includes an implied validation check. command instead, which includes an implied validation check.
## Usage ## Usage
Usage: `terraform validate [options]` Usage: `opentf validate [options]`
This command accepts the following options: This command accepts the following options:
@ -44,17 +44,17 @@ This command accepts the following options:
## JSON Output Format ## JSON Output Format
When you use the `-json` option, Terraform will produce validation results When you use the `-json` option, OpenTF will produce validation results
in JSON format to allow using the validation result for tool integrations, such in JSON format to allow using the validation result for tool integrations, such
as highlighting errors in a text editor. as highlighting errors in a text editor.
As with all JSON output options, it's possible that Terraform will encounter As with all JSON output options, it's possible that OpenTF will encounter
an error prior to beginning the validation task that will thus not be subject an error prior to beginning the validation task that will thus not be subject
to the JSON output setting. For that reason, external software consuming to the JSON output setting. For that reason, external software consuming
Terraform's output should be prepared to find data on stdout that _isn't_ valid OpenTF's output should be prepared to find data on stdout that _isn't_ valid
JSON, which it should then treat as a generic error case. JSON, which it should then treat as a generic error case.
The output includes a `format_version` key, which as of Terraform 1.1.0 has The output includes a `format_version` key, which has
value `"1.0"`. The semantics of this version are: value `"1.0"`. The semantics of this version are:
* We will increment the minor version, e.g. `"1.1"`, for backward-compatible * We will increment the minor version, e.g. `"1.1"`, for backward-compatible
@ -65,43 +65,43 @@ value `"1.0"`. The semantics of this version are:
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). [the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises).
In the normal case, Terraform will print a JSON object to the standard output In the normal case, OpenTF will print a JSON object to the standard output
stream. The top-level JSON object will have the following properties: stream. The top-level JSON object will have the following properties:
- `valid` (boolean): Summarizes the overall validation result, by indicating - `valid` (boolean): Summarizes the overall validation result, by indicating
`true` if Terraform considers the current configuration to be valid or `true` if OpenTF considers the current configuration to be valid or
`false` if it detected any errors. `false` if it detected any errors.
- `error_count` (number): A zero or positive whole number giving the count - `error_count` (number): A zero or positive whole number giving the count
of errors Terraform detected. If `valid` is `true` then `error_count` will of errors OpenTF detected. If `valid` is `true` then `error_count` will
always be zero, because it is the presence of errors that indicates that always be zero, because it is the presence of errors that indicates that
a configuration is invalid. a configuration is invalid.
- `warning_count` (number): A zero or positive whole number giving the count - `warning_count` (number): A zero or positive whole number giving the count
of warnings Terraform detected. Warnings do not cause Terraform to consider of warnings OpenTF detected. Warnings do not cause OpenTF to consider
a configuration to be invalid, but they do indicate potential caveats that a configuration to be invalid, but they do indicate potential caveats that
a user should consider and possibly resolve. a user should consider and possibly resolve.
- `diagnostics` (array of objects): A JSON array of nested objects that each - `diagnostics` (array of objects): A JSON array of nested objects that each
describe an error or warning from Terraform. describe an error or warning from OpenTF.
The nested objects in `diagnostics` have the following properties: The nested objects in `diagnostics` have the following properties:
- `severity` (string): A string keyword, either `"error"` or - `severity` (string): A string keyword, either `"error"` or
`"warning"`, indicating the diagnostic severity. `"warning"`, indicating the diagnostic severity.
The presence of errors causes Terraform to consider a configuration to be The presence of errors causes OpenTF to consider a configuration to be
invalid, while warnings are just advice or caveats to the user which do not invalid, while warnings are just advice or caveats to the user which do not
block working with the configuration. Later versions of Terraform may block working with the configuration. Later versions of OpenTF may
introduce new severity keywords, so consumers should be prepared to accept introduce new severity keywords, so consumers should be prepared to accept
and ignore severity values they don't understand. and ignore severity values they don't understand.
- `summary` (string): A short description of the nature of the problem that - `summary` (string): A short description of the nature of the problem that
the diagnostic is reporting. the diagnostic is reporting.
In Terraform's usual human-oriented diagnostic messages, the summary serves In OpenTF's usual human-oriented diagnostic messages, the summary serves
as a sort of "heading" for the diagnostic, printed after the "Error:" or as a sort of "heading" for the diagnostic, printed after the "Error:" or
"Warning:" indicator. "Warning:" indicator.
@ -114,7 +114,7 @@ The nested objects in `diagnostics` have the following properties:
- `detail` (string): An optional additional message giving more detail about - `detail` (string): An optional additional message giving more detail about
the problem. the problem.
In Terraform's usual human-oriented diagnostic messages, the detail provides In OpenTF's usual human-oriented diagnostic messages, the detail provides
the paragraphs of text that appear after the heading and the source location the paragraphs of text that appear after the heading and the source location
reference. reference.
@ -125,7 +125,7 @@ The nested objects in `diagnostics` have the following properties:
text. Renderers should then soft-wrap the paragraphs to fit the width of the text. Renderers should then soft-wrap the paragraphs to fit the width of the
rendering container, but leave the preformatted lines unwrapped. rendering container, but leave the preformatted lines unwrapped.
Some Terraform detail messages contain an approximation of bullet Some OpenTF detail messages contain an approximation of bullet
lists using ASCII characters to mark the bullets. This is not a lists using ASCII characters to mark the bullets. This is not a
contractural formatting convention, so renderers should avoid depending on contractural formatting convention, so renderers should avoid depending on
it and should instead treat those lines as either paragraphs or preformatted it and should instead treat those lines as either paragraphs or preformatted
@ -155,7 +155,7 @@ The nested objects in `diagnostics` have the following properties:
expression which triggered the diagnostic. For some diagnostics this expression which triggered the diagnostic. For some diagnostics this
information is not available, and then this property will be `null`. information is not available, and then this property will be `null`.
- `code` (string): A snippet of Terraform configuration including the - `code` (string): A snippet of OpenTF configuration including the
source of the diagnostic. This can be multiple lines and may include source of the diagnostic. This can be multiple lines and may include
additional configuration source code around the expression which additional configuration source code around the expression which
triggered the diagnostic. triggered the diagnostic.
@ -210,4 +210,4 @@ exactly which values are responsible for an error. The object has two properties
- `statement` (string): A short English-language fragment describing the value - `statement` (string): A short English-language fragment describing the value
of the expression when the diagnostic was triggered. The contents of this of the expression when the diagnostic was triggered. The contents of this
string are intended to be human-readable and are subject to change in future string are intended to be human-readable and are subject to change in future
versions of Terraform. versions of OpenTF.

27
website/docs/cli/commands/version.mdx
View File

@ -1,54 +1,47 @@
--- ---
page_title: 'Command: version' page_title: 'Command: version'
description: >- description: >-
The terraform version command displays the Terraform version and the version The opentf version command displays the OpenTF version and the version
of all installed plugins. of all installed plugins.
--- ---
# Command: version # Command: version
The `terraform version` displays the current version of Terraform and all The `opentf version` displays the current version of OpenTF and all
installed plugins. installed plugins.
## Usage ## Usage
Usage: `terraform version [options]` Usage: `opentf version [options]`
With no additional arguments, `version` will display the version of Terraform, With no additional arguments, `version` will display the version of OpenTF,
the platform it's installed on, installed providers, and the results of upgrade the platform it's installed on, and installed providers.
and security checks [unless disabled](/terraform/cli/commands#upgrade-and-security-bulletin-checks).
This command has one optional flag: This command has one optional flag:
* `-json` - If specified, the version information is formatted as a JSON object, * `-json` - If specified, the version information is formatted as a JSON object,
and no upgrade or security information is included. and no upgrade or security information is included.
-> **Note:** Platform information was added to the `version` command in Terraform 0.15.
## Example ## Example
Basic usage, with upgrade and security information shown if relevant: Basic usage, with security information shown if relevant:
```shellsession ```shellsession
$ terraform version $ opentf version
Terraform v0.15.0 OpenTF v1.6.0
on darwin_amd64 on darwin_amd64
+ provider registry.terraform.io/hashicorp/null v3.0.0 + provider registry.terraform.io/hashicorp/null v3.0.0
Your version of Terraform is out of date! The latest version
is X.Y.Z. You can update by downloading from https://www.terraform.io/downloads.html
``` ```
As JSON: As JSON:
```shellsession ```shellsession
$ terraform version -json $ opentf version -json
{ {
"terraform_version": "0.15.0", "terraform_version": "0.15.0",
"platform": "darwin_amd64", "platform": "darwin_amd64",
"provider_selections": { "provider_selections": {
"registry.terraform.io/hashicorp/null": "3.0.0" "registry.terraform.io/hashicorp/null": "3.0.0"
}, }
"terraform_outdated": true
} }
``` ```

20
website/docs/cli/commands/workspace/delete.mdx
View File

@ -1,35 +1,35 @@
--- ---
page_title: 'Command: workspace delete' page_title: 'Command: workspace delete'
description: The terraform workspace delete command is used to delete a workspace. description: The opentf workspace delete command is used to delete a workspace.
--- ---
# Command: workspace delete # Command: workspace delete
The `terraform workspace delete` command is used to delete an existing workspace. The `opentf workspace delete` command is used to delete an existing workspace.
## Usage ## Usage
Usage: `terraform workspace delete [OPTIONS] NAME [DIR]` Usage: `opentf workspace delete [OPTIONS] NAME [DIR]`
This command will delete the specified workspace. This command will delete the specified workspace.
To delete a workspace, it must already exist, it must not be tracking resources, To delete a workspace, it must already exist, it must not be tracking resources,
and it must not be your current workspace. If the workspace is tracking resources, and it must not be your current workspace. If the workspace is tracking resources,
Terraform will not allow you to delete it unless the `-force` flag is specified. OpenTF will not allow you to delete it unless the `-force` flag is specified.
Additionally, different [backends](/terraform/language/settings/backends/configuration#backend-types) may implement other Additionally, different [backends](/opentf/language/settings/backends/configuration#backend-types) may implement other
restrictions on whether a workspace is considered safe to delete without the `-force` flag, such as whether the workspace is locked. restrictions on whether a workspace is considered safe to delete without the `-force` flag, such as whether the workspace is locked.
If you delete a workspace which is tracking resources (via `-force`), then resources If you delete a workspace which is tracking resources (via `-force`), then resources
may become "dangling". These are resources that physically exist but that may become "dangling". These are resources that physically exist but that
Terraform can no longer manage. This is sometimes preferred: you may want OpenTF can no longer manage. This is sometimes preferred: you may want
Terraform to stop managing resources, so they can be managed some other way. OpenTF to stop managing resources, so they can be managed some other way.
Most of the time, however, this is not intended and so Terraform protects you Most of the time, however, this is not intended and so OpenTF protects you
from getting into this situation. from getting into this situation.
The command-line flags are all optional. The only supported flags are: The command-line flags are all optional. The only supported flags are:
* `-force` - Delete the workspace even if it is tracking resources. After deletion, Terraform can no longer track or manage the workspace's infrastructure. Defaults to false. * `-force` - Delete the workspace even if it is tracking resources. After deletion, OpenTF can no longer track or manage the workspace's infrastructure. Defaults to false.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
@ -38,6 +38,6 @@ The command-line flags are all optional. The only supported flags are:
## Example ## Example
``` ```
$ terraform workspace delete example $ opentf workspace delete example
Deleted workspace "example". Deleted workspace "example".
``` ```

6
website/docs/cli/commands/workspace/index.mdx
View File

@ -5,13 +5,13 @@ description: The workspace command helps you manage workspaces.
# Command: workspace # Command: workspace
The `terraform workspace` command is used to manage The `opentf workspace` command is used to manage
[workspaces](/terraform/language/state/workspaces). [workspaces](/opentf/language/state/workspaces).
This command is a container for further subcommands that each have their own page in the documentation. This command is a container for further subcommands that each have their own page in the documentation.
## Usage ## Usage
Usage: `terraform workspace <subcommand> [options] [args]` Usage: `opentf workspace <subcommand> [options] [args]`
Choose a subcommand page for more information. Choose a subcommand page for more information.

8
website/docs/cli/commands/workspace/list.mdx
View File

@ -1,15 +1,15 @@
--- ---
page_title: 'Command: workspace list' page_title: 'Command: workspace list'
description: The terraform workspace list command is used to list all existing workspaces. description: The opentf workspace list command is used to list all existing workspaces.
--- ---
# Command: workspace list # Command: workspace list
The `terraform workspace list` command is used to list all existing workspaces. The `opentf workspace list` command is used to list all existing workspaces.
## Usage ## Usage
Usage: `terraform workspace list [DIR]` Usage: `opentf workspace list [DIR]`
The command will list all existing workspaces. The current workspace is The command will list all existing workspaces. The current workspace is
indicated using an asterisk (`*`) marker. indicated using an asterisk (`*`) marker.
@ -17,7 +17,7 @@ indicated using an asterisk (`*`) marker.
## Example ## Example
``` ```
$ terraform workspace list $ opentf workspace list
default default
* development * development
jsmith-test jsmith-test

14
website/docs/cli/commands/workspace/new.mdx
View File

@ -1,15 +1,15 @@
--- ---
page_title: 'Command: workspace new' page_title: 'Command: workspace new'
description: The terraform workspace new command is used to create a new workspace. description: The opentf workspace new command is used to create a new workspace.
--- ---
# Command: workspace new # Command: workspace new
The `terraform workspace new` command is used to create a new workspace. The `opentf workspace new` command is used to create a new workspace.
## Usage ## Usage
Usage: `terraform workspace new [OPTIONS] NAME [DIR]` Usage: `opentf workspace new [OPTIONS] NAME [DIR]`
This command will create a new workspace with the given name. A workspace with This command will create a new workspace with the given name. A workspace with
this name must not already exist. this name must not already exist.
@ -28,11 +28,11 @@ The command-line flags are all optional. The supported flags are:
## Example: Create ## Example: Create
``` ```
$ terraform workspace new example $ opentf workspace new example
Created and switched to workspace "example"! Created and switched to workspace "example"!
You're now on a new, empty workspace. Workspaces isolate their state, You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "terraform plan" Terraform will not see any existing state so if you run "opentf plan" OpenTF will not see any existing state
for this configuration. for this configuration.
``` ```
@ -41,10 +41,10 @@ for this configuration.
To create a new workspace from a pre-existing local state file: To create a new workspace from a pre-existing local state file:
``` ```
$ terraform workspace new -state=old.terraform.tfstate example $ opentf workspace new -state=old.opentf.tfstate example
Created and switched to workspace "example". Created and switched to workspace "example".
You're now on a new, empty workspace. Workspaces isolate their state, You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "terraform plan" Terraform will not see any existing state so if you run "opentf plan" OpenTF will not see any existing state
for this configuration. for this configuration.
``` ```

10
website/docs/cli/commands/workspace/select.mdx
View File

@ -1,16 +1,16 @@
--- ---
page_title: 'Command: workspace select' page_title: 'Command: workspace select'
description: The terraform workspace select command is used to choose a workspace. description: The opentf workspace select command is used to choose a workspace.
--- ---
# Command: workspace select # Command: workspace select
The `terraform workspace select` command is used to choose a different The `opentf workspace select` command is used to choose a different
workspace to use for further operations. workspace to use for further operations.
## Usage ## Usage
Usage: `terraform workspace select NAME [DIR]` Usage: `opentf workspace select NAME [DIR]`
This command will select another workspace. The named workspace must already This command will select another workspace. The named workspace must already
exist. exist.
@ -22,11 +22,11 @@ The supported flags are:
## Example ## Example
``` ```
$ terraform workspace list $ opentf workspace list
default default
* development * development
jsmith-test jsmith-test
$ terraform workspace select default $ opentf workspace select default
Switched to workspace "default". Switched to workspace "default".
``` ```

8
website/docs/cli/commands/workspace/show.mdx
View File

@ -1,21 +1,21 @@
--- ---
page_title: 'Command: workspace show' page_title: 'Command: workspace show'
description: The terraform workspace show command is used to output the current workspace. description: The opentf workspace show command is used to output the current workspace.
--- ---
# Command: workspace show # Command: workspace show
The `terraform workspace show` command is used to output the current workspace. The `opentf workspace show` command is used to output the current workspace.
## Usage ## Usage
Usage: `terraform workspace show` Usage: `opentf workspace show`
The command will display the current workspace. The command will display the current workspace.
## Example ## Example
``` ```
$ terraform workspace show $ opentf workspace show
development development
``` ```

187
website/docs/cli/config/config-file.mdx
View File

@ -8,8 +8,8 @@ description: >-
# CLI Configuration File (`.opentfrc` or `opentf.rc`) # CLI Configuration File (`.opentfrc` or `opentf.rc`)
The CLI configuration file configures per-user settings for CLI behaviors, The CLI configuration file configures per-user settings for CLI behaviors,
which apply across all Terraform working directories. This is separate from which apply across all OpenTF working directories. This is separate from
[your infrastructure configuration](/terraform/language). [your infrastructure configuration](/opentf/language).
## Locations ## Locations
@ -34,8 +34,8 @@ CLI configuration file, even though Windows Explorer may _display_ its name
as just `opentf.rc`. Use `dir` from PowerShell or Command Prompt to as just `opentf.rc`. Use `dir` from PowerShell or Command Prompt to
confirm the filename. confirm the filename.
The location of the Terraform CLI configuration file can also be specified The location of the OpenTF CLI configuration file can also be specified
using the `TF_CLI_CONFIG_FILE` [environment variable](/terraform/cli/config/environment-variables). using the `TF_CLI_CONFIG_FILE` [environment variable](/opentf/cli/config/environment-variables).
Any such file should follow the naming pattern `*.tfrc`. Any such file should follow the naming pattern `*.tfrc`.
## Configuration File Syntax ## Configuration File Syntax
@ -53,12 +53,11 @@ plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
The following settings can be set in the CLI configuration file: The following settings can be set in the CLI configuration file:
* `credentials` - configures credentials for use with Terraform Cloud or * `credentials` - configures credentials for use with a cloud backend.
Terraform Enterprise. See [Credentials](#credentials) below for more See [Credentials](#credentials) below for more information.
information.
* `credentials_helper` - configures an external helper program for the storage * `credentials_helper` - configures an external helper program for the storage
and retrieval of credentials for Terraform Cloud or Terraform Enterprise. and retrieval of credentials for cloud backends.
See [Credentials Helpers](#credentials-helpers) below for more information. See [Credentials Helpers](#credentials-helpers) below for more information.
* `plugin_cache_dir` — enables * `plugin_cache_dir` — enables
@ -66,59 +65,38 @@ The following settings can be set in the CLI configuration file:
and specifies, as a string, the location of the plugin cache directory. and specifies, as a string, the location of the plugin cache directory.
* `provider_installation` - customizes the installation methods used by * `provider_installation` - customizes the installation methods used by
`terraform init` when installing provider plugins. See `opentf init` when installing provider plugins. See
[Provider Installation](#provider-installation) below for more information. [Provider Installation](#provider-installation) below for more information.
## Credentials ## Credentials
[Terraform Cloud](https://cloud.hashicorp.com/products/terraform) provides a number of remote network When interacting with OpenTF-specific network services, OpenTF expects
services for use with Terraform, and
[Terraform Enterprise](/terraform/enterprise) allows hosting those
services inside your own infrastructure. For example, these systems offer both
[remote operations](/terraform/cloud-docs/run/cli) and a
[private module registry](/terraform/cloud-docs/registry).
When interacting with Terraform-specific network services, Terraform expects
to find API tokens in CLI configuration files in `credentials` blocks: to find API tokens in CLI configuration files in `credentials` blocks:
```hcl ```hcl
credentials "app.terraform.io" { credentials "app.placeholderplaceholderplaceholder.io" {
token = "xxxxxx.atlasv1.zzzzzzzzzzzzz" token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
} }
``` ```
If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/terraform/cli/commands/login) If you are running the OpenTF CLI interactively on a computer with a web browser, you can use [the `opentf login` command](/opentf/cli/commands/login)
to get credentials and automatically save them in the CLI configuration. If to get credentials and automatically save them in the CLI configuration. If
not, you can manually write `credentials` blocks. not, you can manually write `credentials` blocks.
You can have multiple `credentials` blocks if you regularly use services from You can have multiple `credentials` blocks if you regularly use services from
multiple hosts. Many users will configure only one, for either multiple hosts. Each `credentials` block contains a `token` argument
Terraform Cloud (at `app.terraform.io`) or for their organization's own
Terraform Enterprise host. Each `credentials` block contains a `token` argument
giving the API token to use for that host. giving the API token to use for that host.
~> **Important:** If you are using Terraform Cloud or Terraform Enterprise,
the token provided must be either a
[user token](/terraform/cloud-docs/users-teams-organizations/users#api-tokens)
or a
[team token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens);
organization tokens cannot be used for command-line Terraform actions.
-> **Note:** The credentials hostname must match the hostname in your module -> **Note:** The credentials hostname must match the hostname in your module
sources and/or backend configuration. If your Terraform Enterprise instance sources and/or backend configuration.
is available at multiple hostnames, use only one of them consistently.
Terraform Cloud responds to API calls at both its current hostname
`app.terraform.io`, and its historical hostname `atlas.hashicorp.com`.
### Environment Variable Credentials ### Environment Variable Credentials
-> **Note:** Environment variable credentials are supported in Terraform v1.2.0 and later.
If you would prefer not to store your API tokens directly in the CLI configuration, you may use If you would prefer not to store your API tokens directly in the CLI configuration, you may use
a host-specific environment variable. Environment variable names should have the prefix a host-specific environment variable. Environment variable names should have the prefix
`TF_TOKEN_` added to the domain name, with periods encoded as underscores. For example, the `TF_TOKEN_` added to the domain name, with periods encoded as underscores. For example, the
value of a variable named `TF_TOKEN_app_terraform_io` will be used as a bearer authorization value of a variable named `TF_TOKEN_app_placeholderplaceholderplaceholder_io` will be used as a bearer authorization
token when the CLI makes service requests to the hostname `app.terraform.io`. token when the CLI makes service requests to the hostname `app.placeholderplaceholderplaceholder.io`.
You must convert domain names containing non-ASCII characters to their [punycode equivalent](https://www.charset.org/punycode) You must convert domain names containing non-ASCII characters to their [punycode equivalent](https://www.charset.org/punycode)
with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable
@ -127,12 +105,12 @@ called `TF_TOKEN_xn--r8j3dr99h_com`.
Hyphens are also valid within host names but usually invalid as variable names and Hyphens are also valid within host names but usually invalid as variable names and
may be encoded as double underscores. For example, you can set a token for the domain name may be encoded as double underscores. For example, you can set a token for the domain name
`café.fr` as `TF_TOKEN_xn--caf-dma.fr`, `TF_TOKEN_xn--caf-dma_fr`, or `TF_TOKEN_xn____caf__dma_fr`. `café.fr` as `TF_TOKEN_xn--caf-dma.fr`, `TF_TOKEN_xn--caf-dma_fr`, or `TF_TOKEN_xn____caf__dma_fr`.
If multiple variables evaluate to the same hostname, Terraform will choose the one defined last If multiple variables evaluate to the same hostname, OpenTF will choose the one defined last
in the operating system's variable table. in the operating system's variable table.
### Credentials Helpers ### Credentials Helpers
You can configure a `credentials_helper` to instruct Terraform to use a different credentials storage mechanism. You can configure a `credentials_helper` to instruct OpenTF to use a different credentials storage mechanism.
```hcl ```hcl
credentials_helper "example" { credentials_helper "example" {
@ -153,43 +131,39 @@ Conversely, this means you can override the credentials returned by the helper
for a specific hostname by writing a `credentials` block alongside the for a specific hostname by writing a `credentials` block alongside the
`credentials_helper` block. `credentials_helper` block.
Terraform does not include any credentials helpers in the main distribution. OpenTF does not include any credentials helpers in the main distribution.
To learn how to write and install your own credentials helpers to integrate To learn how to write and install your own credentials helpers to integrate
with existing in-house credentials management systems, see with existing in-house credentials management systems, see
[the guide to Credentials Helper internals](/terraform/internals/credentials-helpers). [the guide to Credentials Helper internals](/opentf/internals/credentials-helpers).
### Credentials Source Priority Order ### Credentials Source Priority Order
Credentials found in an environment variable for a particular service host Credentials found in an environment variable for a particular service host
as described above will be preferred over those in CLI config as set by `terraform login`. as described above will be preferred over those in CLI config as set by `opentf login`.
If neither are set, any configured credentials helper will be consulted. If neither are set, any configured credentials helper will be consulted.
~> **Note:** For users of [terraform-credentials-helper](https://github.com/apparentlymart/terraform-credentials-env), this priority has been effectively reversed following the
release of Terraform 1.2. Previously, credentials found within CLI config or set by
`terraform login` were preferred to `TF_TOKEN_*` variables.
## Provider Installation ## Provider Installation
The default way to install provider plugins is from a provider registry. The The default way to install provider plugins is from a provider registry. The
origin registry for a provider is encoded in the provider's source address, origin registry for a provider is encoded in the provider's source address,
like `registry.terraform.io/hashicorp/aws`. For convenience in the common case, like `registry.terraform.io/hashicorp/aws`. For convenience in the common case,
Terraform allows omitting the hostname portion for providers on OpenTF allows omitting the hostname portion for providers on
`registry.terraform.io`, so you can write shorter public provider addresses like `registry.terraform.io`, so you can write shorter public provider addresses like
`hashicorp/aws`. `hashicorp/aws`.
Downloading a plugin directly from its origin registry is not always Downloading a plugin directly from its origin registry is not always
appropriate, though. For example, the system where you are running Terraform appropriate, though. For example, the system where you are running OpenTF
may not be able to access an origin registry due to firewall restrictions may not be able to access an origin registry due to firewall restrictions
within your organization or your locality. within your organization or your locality.
To allow using Terraform providers in these situations, there are some To allow using OpenTF providers in these situations, there are some
alternative options for making provider plugins available to Terraform which alternative options for making provider plugins available to OpenTF which
we'll describe in the following sections. we'll describe in the following sections.
### Explicit Installation Method Configuration ### Explicit Installation Method Configuration
A `provider_installation` block in the CLI configuration allows overriding A `provider_installation` block in the CLI configuration allows overriding
Terraform's default installation behaviors, so you can force Terraform to use OpenTF's default installation behaviors, so you can force OpenTF to use
a local mirror for some or all of the providers you intend to use. a local mirror for some or all of the providers you intend to use.
The general structure of a `provider_installation` block is as follows: The general structure of a `provider_installation` block is as follows:
@ -238,7 +212,7 @@ The following are the two supported installation method types:
providers. This method requires the additional argument `path` to indicate providers. This method requires the additional argument `path` to indicate
which directory to look in. which directory to look in.
Terraform expects the given directory to contain a nested directory structure OpenTF expects the given directory to contain a nested directory structure
where the path segments together provide metadata about the available where the path segments together provide metadata about the available
providers. The following two directory structures are supported: providers. The following two directory structures are supported:
@ -251,10 +225,10 @@ The following are the two supported installation method types:
specifies a particular target platform using a format like `darwin_amd64`, specifies a particular target platform using a format like `darwin_amd64`,
`linux_arm`, `windows_amd64`, etc. `linux_arm`, `windows_amd64`, etc.
If you use the unpacked layout, Terraform will attempt to create a symbolic If you use the unpacked layout, OpenTF will attempt to create a symbolic
link to the mirror directory when installing the provider, rather than link to the mirror directory when installing the provider, rather than
creating a deep copy of the directory. The packed layout prevents this creating a deep copy of the directory. The packed layout prevents this
because Terraform must extract the zip file during installation. because OpenTF must extract the zip file during installation.
You can include multiple `filesystem_mirror` blocks in order to specify You can include multiple `filesystem_mirror` blocks in order to specify
several different directories to search. several different directories to search.
@ -264,8 +238,8 @@ The following are the two supported installation method types:
additional argument `url` to indicate the mirror base URL, which should additional argument `url` to indicate the mirror base URL, which should
use the `https:` scheme and end with a trailing slash. use the `https:` scheme and end with a trailing slash.
Terraform expects the given URL to be a base URL for an implementation of OpenTF expects the given URL to be a base URL for an implementation of
[the provider network mirror protocol](/terraform/internals/provider-network-mirror-protocol), [the provider network mirror protocol](/opentf/internals/provider-network-mirror-protocol),
which is designed to be relatively easy to implement using typical static which is designed to be relatively easy to implement using typical static
website hosting mechanisms. website hosting mechanisms.
@ -274,23 +248,23 @@ Provider mirror servers are subject to TLS certificate checks to verify
identity, but a network mirror with a TLS certificate can potentially serve identity, but a network mirror with a TLS certificate can potentially serve
modified copies of upstream providers with malicious content. modified copies of upstream providers with malicious content.
Terraform will try all of the specified methods whose include and exclude OpenTF will try all of the specified methods whose include and exclude
patterns match a given provider, and select the newest version available across patterns match a given provider, and select the newest version available across
all of those methods that matches the version constraint given in each all of those methods that matches the version constraint given in each
Terraform configuration. If you have a local mirror of a particular provider OpenTF configuration. If you have a local mirror of a particular provider
and intend Terraform to use that local mirror exclusively, you must either and intend OpenTF to use that local mirror exclusively, you must either
remove the `direct` installation method altogether or use its `exclude` remove the `direct` installation method altogether or use its `exclude`
argument to disable its use for specific providers. argument to disable its use for specific providers.
### Implied Local Mirror Directories ### Implied Local Mirror Directories
If your CLI configuration does not include a `provider_installation` block at If your CLI configuration does not include a `provider_installation` block at
all, Terraform produces an _implied_ configuration. The implied configuration all, OpenTF produces an _implied_ configuration. The implied configuration
includes a selection of `filesystem_mirror` methods and then the `direct` includes a selection of `filesystem_mirror` methods and then the `direct`
method. method.
The set of directories Terraform can select as filesystem mirrors depends on The set of directories OpenTF can select as filesystem mirrors depends on
the operating system where you are running Terraform: the operating system where you are running OpenTF:
* **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins` * **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins`
* **Mac OS X:** `$HOME/.terraform.d/plugins`, * **Mac OS X:** `$HOME/.terraform.d/plugins`,
@ -300,21 +274,21 @@ the operating system where you are running Terraform:
`terraform/plugins` located within a valid `terraform/plugins` located within a valid
[XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
data directory such as `$XDG_DATA_HOME/terraform/plugins`. data directory such as `$XDG_DATA_HOME/terraform/plugins`.
Without any XDG environment variables set, Terraform will use Without any XDG environment variables set, OpenTF will use
`~/.local/share/terraform/plugins`, `~/.local/share/terraform/plugins`,
`/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`. `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`.
If a `terraform.d/plugins` directory exists in the current working directory If a `terraform.d/plugins` directory exists in the current working directory
then Terraform will also include that directory, regardless of your operating then OpenTF will also include that directory, regardless of your operating
system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, Terraform checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`. system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, OpenTF checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`.
Terraform will check each of the paths above to see if it exists, and if so OpenTF will check each of the paths above to see if it exists, and if so
treat it as a filesystem mirror. The directory structure inside each one must treat it as a filesystem mirror. The directory structure inside each one must
therefore match one of the two structures described for `filesystem_mirror` therefore match one of the two structures described for `filesystem_mirror`
blocks in [Explicit Installation Method Configuration](#explicit-installation-method-configuration). blocks in [Explicit Installation Method Configuration](#explicit-installation-method-configuration).
In addition to the zero or more implied `filesystem_mirror` blocks, Terraform In addition to the zero or more implied `filesystem_mirror` blocks, OpenTF
also creates an implied `direct` block. Terraform will scan all of the also creates an implied `direct` block. OpenTF will scan all of the
filesystem mirror directories to see which providers are placed there and filesystem mirror directories to see which providers are placed there and
automatically exclude all of those providers from the implied `direct` block. automatically exclude all of those providers from the implied `direct` block.
(This automatic `exclude` behavior applies only to _implicit_ `direct` blocks; (This automatic `exclude` behavior applies only to _implicit_ `direct` blocks;
@ -323,14 +297,14 @@ exclusions out yourself.)
### Provider Plugin Cache ### Provider Plugin Cache
By default, `terraform init` downloads plugins into a subdirectory of the By default, `opentf init` downloads plugins into a subdirectory of the
working directory so that each working directory is self-contained. As a working directory so that each working directory is self-contained. As a
consequence, if you have multiple configurations that use the same provider consequence, if you have multiple configurations that use the same provider
then a separate copy of its plugin will be downloaded for each configuration. then a separate copy of its plugin will be downloaded for each configuration.
Given that provider plugins can be quite large (on the order of hundreds of Given that provider plugins can be quite large (on the order of hundreds of
megabytes), this default behavior can be inconvenient for those with slow megabytes), this default behavior can be inconvenient for those with slow
or metered Internet connections. Therefore Terraform optionally allows the or metered Internet connections. Therefore OpenTF optionally allows the
use of a local directory as a shared plugin cache, which then allows each use of a local directory as a shared plugin cache, which then allows each
distinct plugin binary to be downloaded only once. distinct plugin binary to be downloaded only once.
@ -341,8 +315,8 @@ the CLI configuration file. For example:
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
``` ```
This directory must already exist before Terraform will cache plugins; This directory must already exist before OpenTF will cache plugins;
Terraform will not create the directory itself. OpenTF will not create the directory itself.
Please note that on Windows it is necessary to use forward slash separators Please note that on Windows it is necessary to use forward slash separators
(`/`) rather than the conventional backslash (`\`) since the configuration (`/`) rather than the conventional backslash (`\`) since the configuration
@ -357,16 +331,16 @@ directory within a particular shell session:
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache" export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
``` ```
When a plugin cache directory is enabled, the `terraform init` command will When a plugin cache directory is enabled, the `opentf init` command will
still use the configured or implied installation methods to obtain metadata still use the configured or implied installation methods to obtain metadata
about which plugins are available, but once a suitable version has been about which plugins are available, but once a suitable version has been
selected it will first check to see if the chosen plugin is already available selected it will first check to see if the chosen plugin is already available
in the cache directory. If so, Terraform will use the previously-downloaded in the cache directory. If so, OpenTF will use the previously-downloaded
copy. copy.
If the selected plugin is not already in the cache, Terraform will download If the selected plugin is not already in the cache, OpenTF will download
it into the cache first and then copy it from there into the correct location it into the cache first and then copy it from there into the correct location
under your current working directory. When possible Terraform will use under your current working directory. When possible OpenTF will use
symbolic links to avoid storing a separate copy of a cached plugin in multiple symbolic links to avoid storing a separate copy of a cached plugin in multiple
directories. directories.
@ -374,12 +348,12 @@ The plugin cache directory _must not_ also be one of the configured or implied
filesystem mirror directories, since the cache management logic conflicts with filesystem mirror directories, since the cache management logic conflicts with
the filesystem mirror logic when operating on the same directory. the filesystem mirror logic when operating on the same directory.
Terraform will never itself delete a plugin from the plugin cache once it has OpenTF will never itself delete a plugin from the plugin cache once it has
been placed there. Over time, as plugins are upgraded, the cache directory may been placed there. Over time, as plugins are upgraded, the cache directory may
grow to contain several unused versions which you must delete manually. grow to contain several unused versions which you must delete manually.
-> **Note:** The plugin cache directory is not guaranteed to be concurrency -> **Note:** The plugin cache directory is not guaranteed to be concurrency
safe. The provider installer's behavior in environments with multiple `terraform safe. The provider installer's behavior in environments with multiple `opentf
init` calls is undefined. init` calls is undefined.
### Allowing the Provider Plugin Cache to break the dependency lock file ### Allowing the Provider Plugin Cache to break the dependency lock file
@ -388,21 +362,21 @@ init` calls is undefined.
only. Do not set this option unless you are sure you need it and you fully only. Do not set this option unless you are sure you need it and you fully
understand the consequences of enabling it. understand the consequences of enabling it.
By default Terraform will use packages from the global cache directory only By default OpenTF will use packages from the global cache directory only
if they match at least one of the checksums recorded in the if they match at least one of the checksums recorded in the
[dependency lock file](/terraform/language/files/dependency-lock) [dependency lock file](/opentf/language/files/dependency-lock)
for that provider. This ensures that Terraform can always for that provider. This ensures that OpenTF can always
generate a complete and correct dependency lock file entry the first time you generate a complete and correct dependency lock file entry the first time you
use a new provider in a particular configuration. use a new provider in a particular configuration.
However, we know that in some special situations teams have been unable to use However, we know that in some special situations teams have been unable to use
the dependency lock file as intended, and so they don't include it in their the dependency lock file as intended, and so they don't include it in their
version control as recommended and instead let Terraform re-generate it each version control as recommended and instead let OpenTF re-generate it each
time it installs providers. time it installs providers.
For those teams that don't preserve the dependency lock file in their version For those teams that don't preserve the dependency lock file in their version
control systems between runs, Terraform allows an additional CLI Configuration control systems between runs, OpenTF allows an additional CLI Configuration
setting which tells Terraform to always treat a package in the cache directory setting which tells OpenTF to always treat a package in the cache directory
as valid even if there isn't already an entry in the dependency lock file as valid even if there isn't already an entry in the dependency lock file
to confirm it: to confirm it:
@ -414,19 +388,19 @@ Alternatively, you can set the environment variable
`TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to any value other than the `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to any value other than the
empty string or `0`, which is equivalent to the above setting. empty string or `0`, which is equivalent to the above setting.
Setting this option gives Terraform CLI permission to create an incomplete Setting this option gives OpenTF CLI permission to create an incomplete
dependency lock file entry for a provider if that would allow Terraform to dependency lock file entry for a provider if that would allow OpenTF to
use the cache to install that provider. In that situation the dependency lock use the cache to install that provider. In that situation the dependency lock
file will be valid for use on the current system but may not be valid for use on file will be valid for use on the current system but may not be valid for use on
another computer with a different operating system or CPU architecture, because another computer with a different operating system or CPU architecture, because
it will include only a checksum of the package in the global cache. it will include only a checksum of the package in the global cache.
We recommend that most users leave this option unset, in which case Terraform We recommend that most users leave this option unset, in which case OpenTF
will always install a provider from upstream the first time you use it with will always install a provider from upstream the first time you use it with
a particular configuration, but can then re-use the cache entry on later runs a particular configuration, but can then re-use the cache entry on later runs
once the dependency lock file records valid checksums for the provider package. once the dependency lock file records valid checksums for the provider package.
~> **Note:** The Terraform team intends to improve the dependency lock file ~> **Note:** The OpenTF team intends to improve the dependency lock file
mechanism in future versions so that it will be usable in more situations. At mechanism in future versions so that it will be usable in more situations. At
that time this option will become silently ignored. If your workflow relies on that time this option will become silently ignored. If your workflow relies on
the use of this option, please open a GitHub issue to share details about your the use of this option, please open a GitHub issue to share details about your
@ -435,11 +409,7 @@ dependency lock file.
### Development Overrides for Provider Developers ### Development Overrides for Provider Developers
-> **Note:** Development overrides work only in Terraform v0.14 and later. Normally OpenTF verifies version selections and checksums for providers
Using a `dev_overrides` block in your CLI configuration will cause Terraform
v0.13 to reject the configuration as invalid.
Normally Terraform verifies version selections and checksums for providers
in order to help ensure that all operations are made with the intended version in order to help ensure that all operations are made with the intended version
of a provider, and that authors can gradually upgrade to newer provider versions of a provider, and that authors can gradually upgrade to newer provider versions
in a controlled manner. in a controlled manner.
@ -449,7 +419,7 @@ though, because we often want to try a test configuration against a development
build of a provider that doesn't even have an associated version number yet, build of a provider that doesn't even have an associated version number yet,
and doesn't have an official set of checksums listed in a provider registry. and doesn't have an official set of checksums listed in a provider registry.
As a convenience for provider development, Terraform supports a special As a convenience for provider development, OpenTF supports a special
additional block `dev_overrides` in `provider_installation` blocks. The contents additional block `dev_overrides` in `provider_installation` blocks. The contents
of this block effectively override all of the other configured installation of this block effectively override all of the other configured installation
methods, so a block of this type must always appear first in the sequence: methods, so a block of this type must always appear first in the sequence:
@ -459,27 +429,27 @@ provider_installation {
# Use /home/developer/tmp/terraform-null as an overridden package directory # Use /home/developer/tmp/terraform-null as an overridden package directory
# for the hashicorp/null provider. This disables the version and checksum # for the hashicorp/null provider. This disables the version and checksum
# verifications for this provider and forces Terraform to look for the # verifications for this provider and forces OpenTF to look for the
# null provider plugin in the given directory. # null provider plugin in the given directory.
dev_overrides { dev_overrides {
"hashicorp/null" = "/home/developer/tmp/terraform-null" "hashicorp/null" = "/home/developer/tmp/terraform-null"
} }
# For all other providers, install them directly from their origin provider # For all other providers, install them directly from their origin provider
# registries as normal. If you omit this, Terraform will _only_ use # registries as normal. If you omit this, OpenTF will _only_ use
# the dev_overrides block, and so no other providers will be available. # the dev_overrides block, and so no other providers will be available.
direct {} direct {}
} }
``` ```
With development overrides in effect, the `terraform init` command will still With development overrides in effect, the `opentf init` command will still
attempt to select a suitable published version of your provider to install and attempt to select a suitable published version of your provider to install and
record in record in
[the dependency lock file](/terraform/language/files/dependency-lock) [the dependency lock file](/opentf/language/files/dependency-lock)
for future use, but other commands like for future use, but other commands like
`terraform apply` will disregard the lock file's entry for `hashicorp/null` and `opentf apply` will disregard the lock file's entry for `hashicorp/null` and
will use the given directory instead. Once your new changes are included in a will use the given directory instead. Once your new changes are included in a
published release of the provider, you can use `terraform init -upgrade` to published release of the provider, you can use `opentf init -upgrade` to
select the new version in the dependency lock file and remove your development select the new version in the dependency lock file and remove your development
override. override.
@ -494,7 +464,7 @@ You may wish to enable a development override only for shell sessions where
you are actively working on provider development. If so, you can write a you are actively working on provider development. If so, you can write a
local CLI configuration file with content like the above in your development local CLI configuration file with content like the above in your development
directory, perhaps called `dev.tfrc` for the sake of example, and then use the directory, perhaps called `dev.tfrc` for the sake of example, and then use the
`TF_CLI_CONFIG_FILE` environment variable to instruct Terraform to use that `TF_CLI_CONFIG_FILE` environment variable to instruct OpenTF to use that
localized CLI configuration instead of the default one: localized CLI configuration instead of the default one:
``` ```
@ -502,7 +472,7 @@ export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc
``` ```
Development overrides are not intended for general use as a way to have Development overrides are not intended for general use as a way to have
Terraform look for providers on the local filesystem. If you wish to put OpenTF look for providers on the local filesystem. If you wish to put
copies of _released_ providers in your local filesystem, see copies of _released_ providers in your local filesystem, see
[Implied Local Mirror Directories](#implied-local-mirror-directories) [Implied Local Mirror Directories](#implied-local-mirror-directories)
or or
@ -512,17 +482,6 @@ instead.
This development overrides mechanism is intended as a pragmatic way to enable This development overrides mechanism is intended as a pragmatic way to enable
smoother provider development. The details of how it behaves, how to smoother provider development. The details of how it behaves, how to
configure it, and how it interacts with the dependency lock file may all evolve configure it, and how it interacts with the dependency lock file may all evolve
in future Terraform releases, including possible breaking changes. We therefore in future OpenTF releases, including possible breaking changes. We therefore
recommend using development overrides only temporarily during provider recommend using development overrides only temporarily during provider
development work. development work.
## Removed Settings
The following settings are supported in Terraform 0.12 and earlier but are
no longer recommended for use:
* `providers` - a configuration block that allows specifying the locations of
specific plugins for each named provider. This mechanism is deprecated
because it is unable to specify a version number and source for each provider.
See [Provider Installation](#provider-installation) above for the replacement
of this setting in Terraform 0.13 and later.

60
website/docs/cli/config/environment-variables.mdx
View File

@ -1,15 +1,15 @@
--- ---
page_title: Environment Variables page_title: Environment Variables
description: >- description: >-
Learn to use environment variables to change Terraform's default behavior. Learn to use environment variables to change OpenTF's default behavior.
Configure log content and output, set variables, and more. Configure log content and output, set variables, and more.
--- ---
# Environment Variables # Environment Variables
Terraform refers to a number of environment variables to customize various OpenTF refers to a number of environment variables to customize various
aspects of its behavior. None of these environment variables are required aspects of its behavior. None of these environment variables are required
when using Terraform, but they can be used to change some of Terraform's when using OpenTF, but they can be used to change some of OpenTF's
default behaviors in unusual situations, or to increase output verbosity default behaviors in unusual situations, or to increase output verbosity
for debugging. for debugging.
@ -27,21 +27,21 @@ To disable, either unset it, or set it to `off`. For example:
export TF_LOG=off export TF_LOG=off
``` ```
For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging). For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging).
## TF_LOG_PATH ## TF_LOG_PATH
This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running terraform from: This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running opentf from:
```shell ```shell
export TF_LOG_PATH=./terraform.log export TF_LOG_PATH=./terraform.log
``` ```
For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging). For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging).
## TF_INPUT ## TF_INPUT
If set to "false" or "0", causes terraform commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example: If set to "false" or "0", causes opentf commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example:
```shell ```shell
export TF_INPUT=0 export TF_INPUT=0
@ -58,7 +58,7 @@ export TF_VAR_alist='[1,2,3]'
export TF_VAR_amap='{ foo = "bar", baz = "qux" }' export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
``` ```
For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/terraform/language/values/variables). For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/opentf/language/values/variables).
## TF_CLI_ARGS and TF_CLI_ARGS_name ## TF_CLI_ARGS and TF_CLI_ARGS_name
@ -66,17 +66,17 @@ For more on how to use `TF_VAR_name` in context, check out the section on [Varia
The value of `TF_CLI_ARGS` will specify additional arguments to the The value of `TF_CLI_ARGS` will specify additional arguments to the
command-line. This allows easier automation in CI environments as well as command-line. This allows easier automation in CI environments as well as
modifying default behavior of Terraform on your own system. modifying default behavior of OpenTF on your own system.
These arguments are inserted directly _after_ the subcommand These arguments are inserted directly _after_ the subcommand
(such as `plan`) and _before_ any flags specified directly on the command-line. (such as `plan`) and _before_ any flags specified directly on the command-line.
This behavior ensures that flags on the command-line take precedence over This behavior ensures that flags on the command-line take precedence over
environment variables. environment variables.
For example, the following command: `TF_CLI_ARGS="-input=false" terraform apply -force` For example, the following command: `TF_CLI_ARGS="-input=false" opentf apply -force`
is the equivalent to manually typing: `terraform apply -input=false -force`. is the equivalent to manually typing: `opentf apply -input=false -force`.
The flag `TF_CLI_ARGS` affects all Terraform commands. If you specify a The flag `TF_CLI_ARGS` affects all OpenTF commands. If you specify a
named command in the form of `TF_CLI_ARGS_name` then it will only affect named command in the form of `TF_CLI_ARGS_name` then it will only affect
that command. As an example, to specify that only plans never refresh, that command. As an example, to specify that only plans never refresh,
you can set `TF_CLI_ARGS_plan="-refresh=false"`. you can set `TF_CLI_ARGS_plan="-refresh=false"`.
@ -87,7 +87,7 @@ be separated by spaces otherwise.
## TF_DATA_DIR ## TF_DATA_DIR
`TF_DATA_DIR` changes the location where Terraform keeps its `TF_DATA_DIR` changes the location where OpenTF keeps its
per-working-directory data, such as the current backend configuration. per-working-directory data, such as the current backend configuration.
By default this data is written into a `.terraform` subdirectory of the By default this data is written into a `.terraform` subdirectory of the
@ -99,12 +99,12 @@ be useful to do so if e.g. the working directory is not writable.
The data directory is used to retain data that must persist from one command The data directory is used to retain data that must persist from one command
to the next, so it's important to have this variable set consistently throughout to the next, so it's important to have this variable set consistently throughout
all of the Terraform workflow commands (starting with `terraform init`) or else all of the OpenTF workflow commands (starting with `opentf init`) or else
Terraform may be unable to find providers, modules, and other artifacts. OpenTF may be unable to find providers, modules, and other artifacts.
## TF_WORKSPACE ## TF_WORKSPACE
For multi-environment deployment, in order to select a workspace, instead of doing `terraform workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection. For multi-environment deployment, in order to select a workspace, instead of doing `opentf workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection.
For example: For example:
@ -114,20 +114,18 @@ export TF_WORKSPACE=your_workspace
Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state. Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state.
For more information regarding workspaces, check out the section on [Using Workspaces](/terraform/language/state/workspaces). For more information regarding workspaces, check out the section on [Using Workspaces](/opentf/language/state/workspaces).
## TF_IN_AUTOMATION ## TF_IN_AUTOMATION
If `TF_IN_AUTOMATION` is set to any non-empty value, Terraform adjusts its If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTF adjusts its
output to avoid suggesting specific commands to run next. This can make the output to avoid suggesting specific commands to run next. This can make the
output more consistent and less confusing in workflows where users don't output more consistent and less confusing in workflows where users don't
directly execute Terraform commands, like in CI systems or other wrapping directly execute OpenTF commands, like in CI systems or other wrapping
applications. applications.
This is a purely cosmetic change to Terraform's human-readable output, and the This is a purely cosmetic change to OpenTF's human-readable output, and the
exact output differences can change between minor Terraform versions. exact output differences can change between minor OpenTF versions.
For more details, see [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
## TF_REGISTRY_DISCOVERY_RETRY ## TF_REGISTRY_DISCOVERY_RETRY
@ -145,7 +143,7 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15
## TF_CLI_CONFIG_FILE ## TF_CLI_CONFIG_FILE
The location of the [Terraform CLI configuration file](/terraform/cli/config/config-file). The location of the [OpenTF CLI configuration file](/opentf/cli/config/config-file).
```shell ```shell
export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom" export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom"
@ -153,22 +151,22 @@ export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom"
## TF_PLUGIN_CACHE_DIR ## TF_PLUGIN_CACHE_DIR
The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](/terraform/cli/config/config-file#provider-plugin-cache). The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](/opentf/cli/config/config-file#provider-plugin-cache).
You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](/terraform/cli/config/config-file#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file). You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](/opentf/cli/config/config-file#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file).
## TF_IGNORE ## TF_IGNORE
If `TF_IGNORE` is set to "trace", Terraform will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files. If `TF_IGNORE` is set to "trace", OpenTF will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files.
```shell ```shell
export TF_IGNORE=trace export TF_IGNORE=trace
``` ```
For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/terraform/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore). For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/opentf/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore).
## Terraform Cloud CLI Integration ## Cloud Backend CLI Integration
The CLI integration with Terraform Cloud lets you use Terraform Cloud and Terraform Enterprise on the command line. The integration requires including a `cloud` block in your Terraform configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI). The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTF configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).
Refer to [Terraform Cloud Settings](/terraform/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables. Refer to [Cloud Backend Settings](/opentf/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables.

18
website/docs/cli/config/index.mdx
View File

@ -1,24 +1,24 @@
--- ---
page_title: CLI Configuration - Terraform CLI page_title: CLI Configuration - OpenTF CLI
description: >- description: >-
Find documentation about the CLI config file and customizing Terraform Find documentation about the CLI config file and customizing OpenTF
environment variables. environment variables.
--- ---
# CLI Configuration # CLI Configuration
Terraform CLI can be configured with some global settings, which are separate OpenTF CLI can be configured with some global settings, which are separate
from any Terraform configuration and which apply across all working directories. from any OpenTF configuration and which apply across all working directories.
We've designed Terraform such that an average user running Terraform CLI We've designed OpenTF such that an average user running OpenTF CLI
interactively will not need to interact with any of these settings. As a result, interactively will not need to interact with any of these settings. As a result,
most of the global settings relate to advanced or automated workflows, or most of the global settings relate to advanced or automated workflows, or
unusual environmental conditions like running Terraform on an airgapped unusual environmental conditions like running OpenTF on an airgapped
instance. instance.
- The [CLI config file](/terraform/cli/config/config-file) configures provider - The [CLI config file](/opentf/cli/config/config-file) configures provider
installation and security features. installation and security features.
- Several [environment variables](/terraform/cli/config/environment-variables) can - Several [environment variables](/opentf/cli/config/environment-variables) can
configure Terraform's inputs and outputs; this includes some alternate ways to configure OpenTF's inputs and outputs; this includes some alternate ways to
provide information that is usually passed on the command line or read from provide information that is usually passed on the command line or read from
the state of the shell. the state of the shell.

12
website/docs/cli/import/importability.mdx
View File

@ -1,16 +1,16 @@
--- ---
page_title: 'Import: Resource Importability' page_title: 'Import: Resource Importability'
description: |- description: |-
Each resource in Terraform must implement some basic logic to become Each resource in OpenTF must implement some basic logic to become
importable. As a result, you cannot import all Terraform resources. importable. As a result, you cannot import all OpenTF resources.
--- ---
# Resource Importability # Resource Importability
Each resource in Terraform must implement some basic logic to become Each resource in OpenTF must implement some basic logic to become
importable. As a result, you cannot import all Terraform resources. importable. As a result, you cannot import all OpenTF resources.
The resources that you can import are documented at the bottom of The resources that you can import are documented at the bottom of
each resource documentation page in the [Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository. each resource documentation page in the [public Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository.
To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import). To make a resource importable, refer to [Extending OpenTF: Resources — Import](/opentf/plugin/sdkv2/resources/import).

20
website/docs/cli/import/index.mdx
View File

@ -1,26 +1,24 @@
--- ---
page_title: Import page_title: Import
description: >- description: >-
Terraform can import and manage existing infrastructure. This can help you OpenTF can import and manage existing infrastructure. This can help you
transition your infrastructure to Terraform. transition your infrastructure to OpenTF.
--- ---
# Import # Import
> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. OpenTF can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTF management.
Terraform can import existing infrastructure resources. This functionality lets you bring existing resources under Terraform management. -> **Note:** OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/opentf/language/import).
-> **Note:** Terraform v1.5.0 and later supports `import` blocks. Unlike the `terraform import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/terraform/language/import).
## State Only ## State Only
~> **Warning:** Terraform expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. See [State](/terraform/language/state) for more details. ~> **Warning:** OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/opentf/language/state) for more details.
The `terraform import` CLI command can only import resources into the [state](/terraform/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/terraform/language/import). The `opentf import` CLI command can only import resources into the [state](/opentf/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/opentf/language/import).
Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. Before you run `opentf import` you must manually write a `resource` configuration block for the resource. The resource block describes where OpenTF should map the imported object.
## Terraform Cloud ## Cloud Backend
When you use Terraform on the command line with Terraform Cloud, many commands like `apply` run inside your Terraform Cloud environment. However, the `import` command runs locally, so it does not have access to information from Terraform Cloud. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in Terraform Cloud. When you use OpenTF on the command line with a cloud backend, many commands like `apply` run inside your cloud backend's environment. However, the `import` command runs locally, so it does not have access to information from the cloud backend. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in the cloud backend.

37
website/docs/cli/import/usage.mdx
View File

@ -1,27 +1,24 @@
--- ---
page_title: 'Import: Usage' page_title: 'Import: Usage'
description: The `terraform import` command is used to import existing infrastructure. description: The `opentf import` command is used to import existing infrastructure.
--- ---
# Import Usage # Import Usage
> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. Use the `opentf import` command to import existing infrastructure to OpenTF state.
The `opentf import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC.
Use the `terraform import` command to import existing infrastructure to Terraform state. ~> Warning: OpenTF expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by OpenTF
The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC. itself having created all objects. If you import existing objects into OpenTF,
be careful to import each remote object to only one OpenTF resource address.
~> Warning: Terraform expects that each remote object it is managing will be If you import the same object multiple times, OpenTF may exhibit unwanted
bound to only one resource address, which is normally guaranteed by Terraform
itself having created all objects. If you import existing objects into Terraform,
be careful to import each remote object to only one Terraform resource address.
If you import the same object multiple times, Terraform may exhibit unwanted
behavior. For more information on this assumption, see behavior. For more information on this assumption, see
[the State section](/terraform/language/state). [the State section](/opentf/language/state).
To import a resource, first write a resource block for it in your To import a resource, first write a resource block for it in your
configuration, establishing the name by which it will be known to Terraform: configuration, establishing the name by which it will be known to OpenTF:
``` ```
resource "aws_instance" "example" { resource "aws_instance" "example" {
@ -37,22 +34,22 @@ remains constant.
If desired, you can leave the body of the resource block blank for now and If desired, you can leave the body of the resource block blank for now and
return to fill it in once the instance is imported. return to fill it in once the instance is imported.
Now `terraform import` can be run to attach an existing instance to this Now `opentf import` can be run to attach an existing instance to this
resource configuration: resource configuration:
```shell ```shell
$ terraform import aws_instance.example i-abcd1234 $ opentf import aws_instance.example i-abcd1234
``` ```
This command locates the AWS EC2 instance with ID `i-abcd1234`. Then it attaches This command locates the AWS EC2 instance with ID `i-abcd1234`. Then it attaches
the existing settings of the instance, as described by the EC2 API, to the the existing settings of the instance, as described by the EC2 API, to the
name `aws_instance.example` of a module. In this example the module path name `aws_instance.example` of a module. In this example the module path
implies that the root module is used. Finally, the mapping is saved in the implies that the root module is used. Finally, the mapping is saved in the
Terraform state. OpenTF state.
It is also possible to import to resources in child modules, using their paths, It is also possible to import to resources in child modules, using their paths,
and to single instances of a resource with `count` or `for_each` set. See and to single instances of a resource with `count` or `for_each` set. See
[_Resource Addressing_](/terraform/cli/state/resource-addressing) for more [_Resource Addressing_](/opentf/cli/state/resource-addressing) for more
details on how to specify a target resource. details on how to specify a target resource.
The syntax of the given ID is dependent on the resource type being imported. The syntax of the given ID is dependent on the resource type being imported.
@ -61,7 +58,7 @@ AWS Route53 Zones use the domain name itself. Consult the documentation for
each importable resource for details on what form of ID is required. each importable resource for details on what form of ID is required.
As a result of the above command, the resource is recorded in the state file. As a result of the above command, the resource is recorded in the state file.
You can now run `terraform plan` to see how the configuration compares to You can now run `opentf plan` to see how the configuration compares to
the imported resource, and make any adjustments to the configuration to the imported resource, and make any adjustments to the configuration to
align with the current (or desired) state of the imported object. align with the current (or desired) state of the imported object.
@ -75,7 +72,7 @@ an `aws_network_acl` but also one `aws_network_acl_rule` for each rule.
In this scenario, the secondary resources will not already exist in In this scenario, the secondary resources will not already exist in
configuration, so it is necessary to consult the import output and create configuration, so it is necessary to consult the import output and create
a `resource` block in configuration for each secondary resource. If this is a `resource` block in configuration for each secondary resource. If this is
not done, Terraform will plan to destroy the imported objects on the next run. not done, OpenTF will plan to destroy the imported objects on the next run.
If you want to rename or otherwise move the imported resources, the If you want to rename or otherwise move the imported resources, the
[state management commands](/terraform/cli/commands/state) can be used. [state management commands](/opentf/cli/commands/state) can be used.

22
website/docs/cli/index.mdx
View File

@ -1,19 +1,17 @@
--- ---
page_title: Terraform CLI Documentation page_title: OpenTF CLI Documentation
description: >- description: >-
Learn Terraform's CLI-based workflows. You can use the CLI alone or Learn OpenTF's CLI-based workflows. You can use the CLI alone or
with Terraform Cloud or Terraform Enterprise. with cloud backends.
--- ---
# Terraform CLI Documentation # OpenTF CLI Documentation
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. This is the documentation for OpenTF CLI. It is relevant to anyone working
with OpenTF's CLI-based workflows; this includes people who use OpenTF CLI
by itself, as well as those who use OpenTF CLI in conjunction with
TACOS (TF Automation and Collaboration Software).
This is the documentation for Terraform CLI. It is relevant to anyone working Notably, this documentation does not cover the syntax and usage of the OpenTF
with Terraform's CLI-based workflows; this includes people who use Terraform CLI
by itself, as well as those who use Terraform CLI in conjunction with Terraform
Cloud or Terraform Enterprise.
Notably, this documentation does not cover the syntax and usage of the Terraform
language. For that, see the language. For that, see the
[Terraform Language Documentation](/terraform/language). [OpenTF Language Documentation](/opentf/language).

38
website/docs/cli/init/index.mdx
View File

@ -1,5 +1,5 @@
--- ---
page_title: Initializing Working Directories - Terraform CLI page_title: Initializing Working Directories - OpenTF CLI
description: >- description: >-
Working directories contain configurations, settings, cached plugins and Working directories contain configurations, settings, cached plugins and
modules, and state data. Learn how to initialize and manage working modules, and state data. Learn how to initialize and manage working
@ -8,37 +8,37 @@ description: >-
# Initializing Working Directories # Initializing Working Directories
Terraform expects to be invoked from a working directory that contains OpenTF expects to be invoked from a working directory that contains
configuration files written in configuration files written in
[the Terraform language](/terraform/language). Terraform uses [the OpenTF language](/opentf/language). OpenTF uses
configuration content from this directory, and also uses the directory to store configuration content from this directory, and also uses the directory to store
settings, cached plugins and modules, and sometimes state data. settings, cached plugins and modules, and sometimes state data.
A working directory must be initialized before Terraform can perform any A working directory must be initialized before OpenTF can perform any
operations in it (like provisioning infrastructure or modifying state). operations in it (like provisioning infrastructure or modifying state).
## Working Directory Contents ## Working Directory Contents
A Terraform working directory typically contains: A OpenTF working directory typically contains:
- A Terraform configuration describing resources Terraform should manage. This - A OpenTF configuration describing resources OpenTF should manage. This
configuration is expected to change over time. configuration is expected to change over time.
- A hidden `.terraform` directory, which Terraform uses to manage cached - A hidden `.terraform` directory, which OpenTF uses to manage cached
provider plugins and modules, record which provider plugins and modules, record which
[workspace](/terraform/cli/workspaces) is currently active, and [workspace](/opentf/cli/workspaces) is currently active, and
record the last known backend configuration in case it needs to migrate state record the last known backend configuration in case it needs to migrate state
on the next run. This directory is automatically managed by Terraform, and is on the next run. This directory is automatically managed by OpenTF, and is
created during initialization. created during initialization.
- State data, if the configuration uses the default `local` backend. This is - State data, if the configuration uses the default `local` backend. This is
managed by Terraform in a `terraform.tfstate` file (if the directory only uses managed by OpenTF in a `terraform.tfstate` file (if the directory only uses
the default workspace) or a `terraform.tfstate.d` directory (if the directory the default workspace) or a `terraform.tfstate.d` directory (if the directory
uses multiple workspaces). uses multiple workspaces).
## Initialization ## Initialization
Run the `terraform init` command to initialize a working directory that contains Run the `opentf init` command to initialize a working directory that contains
a Terraform configuration. After initialization, you will be able to perform a OpenTF configuration. After initialization, you will be able to perform
other commands, like `terraform plan` and `terraform apply`. other commands, like `opentf plan` and `opentf apply`.
If you try to run a command that relies on initialization without first If you try to run a command that relies on initialization without first
initializing, the command will fail with an error and explain that you need to initializing, the command will fail with an error and explain that you need to
@ -50,16 +50,16 @@ plugins, and downloading modules. Under some conditions (usually when changing
from one backend to another), it might ask the user for guidance or from one backend to another), it might ask the user for guidance or
confirmation. confirmation.
For details, see [the `terraform init` command](/terraform/cli/commands/init). For details, see [the `opentf init` command](/opentf/cli/commands/init).
## Reinitialization ## Reinitialization
Certain types of changes to a Terraform configuration can require Certain types of changes to a OpenTF configuration can require
reinitialization before normal operations can continue. This includes changes to reinitialization before normal operations can continue. This includes changes to
provider requirements, module sources or version constraints, and backend provider requirements, module sources or version constraints, and backend
configurations. configurations.
You can reinitialize a directory by running `terraform init` again. In fact, you You can reinitialize a directory by running `opentf init` again. In fact, you
can reinitialize at any time; the init command is idempotent, and will have no can reinitialize at any time; the init command is idempotent, and will have no
effect if no changes are required. effect if no changes are required.
@ -68,7 +68,7 @@ fail with an error and tell you so.
## Reinitializing Only Modules ## Reinitializing Only Modules
The `terraform get` command will download modules referenced in the The `opentf get` command will download modules referenced in the
configuration, but will not perform the other required initialization tasks. configuration, but will not perform the other required initialization tasks.
This command is only useful for niche workflows, and most Terraform users can This command is only useful for niche workflows, and most OpenTF users can
ignore it in favor of `terraform init`. ignore it in favor of `opentf init`.

22
website/docs/cli/inspect/index.mdx
View File

@ -1,5 +1,5 @@
--- ---
page_title: Inspecting Infrastructure - Terraform CLI page_title: Inspecting Infrastructure - OpenTF CLI
description: >- description: >-
Learn commands to inspect dependency information, outputs, etc. Use them for Learn commands to inspect dependency information, outputs, etc. Use them for
integration or to understand your infrastructure. integration or to understand your infrastructure.
@ -7,29 +7,29 @@ description: >-
# Inspecting Infrastructure # Inspecting Infrastructure
Terraform configurations and state data include some highly structured OpenTF configurations and state data include some highly structured
information about the resources they manage; this includes dependency information about the resources they manage; this includes dependency
information, outputs (which are pieces of generated or discovered data that the information, outputs (which are pieces of generated or discovered data that the
configuration's author considers important enough to surface to users), and configuration's author considers important enough to surface to users), and
more. more.
Terraform CLI includes some commands for inspecting or transforming this data. OpenTF CLI includes some commands for inspecting or transforming this data.
You can use these to integrate other tools with Terraform's infrastructure data, You can use these to integrate other tools with OpenTF's infrastructure data,
or just to gain a deeper or more holistic understanding of your infrastructure. or just to gain a deeper or more holistic understanding of your infrastructure.
- [The `terraform graph` command](/terraform/cli/commands/graph) creates a visual - [The `opentf graph` command](/opentf/cli/commands/graph) creates a visual
representation of a configuration or a set of planned changes. representation of a configuration or a set of planned changes.
- [The `terraform output` command](/terraform/cli/commands/output) can get the - [The `opentf output` command](/opentf/cli/commands/output) can get the
values for the top-level [output values](/terraform/language/values/outputs) of values for the top-level [output values](/opentf/language/values/outputs) of
a configuration, which are often helpful when making use of the infrastructure a configuration, which are often helpful when making use of the infrastructure
Terraform has provisioned. OpenTF has provisioned.
- [The `terraform show` command](/terraform/cli/commands/show) can generate - [The `opentf show` command](/opentf/cli/commands/show) can generate
human-readable versions of a state file or plan file, or generate human-readable versions of a state file or plan file, or generate
machine-readable versions that can be integrated with other tools. machine-readable versions that can be integrated with other tools.
- [The `terraform state list` command](/terraform/cli/commands/state/list) can list - [The `opentf state list` command](/opentf/cli/commands/state/list) can list
the resources being managed by the current working directory and workspace, the resources being managed by the current working directory and workspace,
providing a complete or filtered list. providing a complete or filtered list.
- [The `terraform state show` command](/terraform/cli/commands/state/show) can print - [The `opentf state show` command](/opentf/cli/commands/state/show) can print
all of the attributes of a given resource being managed by the current working all of the attributes of a given resource being managed by the current working
directory and workspace, including generated read-only attributes like the directory and workspace, including generated read-only attributes like the
unique ID assigned by the cloud provider. unique ID assigned by the cloud provider.

59
website/docs/cli/install/apt.mdx
View File

@ -1,90 +1,65 @@
--- ---
page_title: APT Packages for Debian and Ubuntu page_title: APT Packages for Debian and Ubuntu
description: >- description: >-
The HashiCorp APT repositories contain distribution-specific Terraform The OpenTF APT repositories contain distribution-specific OpenTF
packages for both Debian and Ubuntu systems. packages for both Debian and Ubuntu systems.
--- ---
# APT Packages for Debian and Ubuntu # APT Packages for Debian and Ubuntu
The primary distribution packages for Terraform are `.zip` archives containing The primary distribution packages for OpenTF are `.zip` archives containing
single executable files that you can extract anywhere on your system. However, single executable files that you can extract anywhere on your system. However,
for easier integration with configuration management tools and other systematic for easier integration with configuration management tools and other systematic
system configuration strategies, we also offer package repositories for system configuration strategies, we also offer package repositories for
Debian and Ubuntu systems, which allow you to install Terraform using the Debian and Ubuntu systems, which allow you to install OpenTF using the
`apt install` command or any other APT frontend. `apt install` command or any other APT frontend.
If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you
might prefer to [install Terraform from our Yum repositories](/terraform/cli/install/yum). might prefer to [install OpenTF from our Yum repositories](/opentf/cli/install/yum).
-> **Note:** The APT repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp
products, rather than just Terraform. Adding these repositories to your
system will, by default, therefore make several other non-Terraform
packages available for installation. That might then mask some packages that
are available for some HashiCorp products in the main Debian and Ubuntu
package repositories.
## Repository Configuration ## Repository Configuration
Please follow the instructions in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide). Please follow the instructions in the [Official Packaging Guide](https://www.placeholderplaceholderplaceholder.com/official-packaging-guide).
## Supported Architectures ## Supported Architectures
The HashiCorp APT server has packages only for the `amd64` The OpenTF APT server has packages only for the `amd64`
architecture, which is also sometimes known as `x86_64`. architecture, which is also sometimes known as `x86_64`.
There are no official packages available for other architectures, such as There are no official packages available for other architectures, such as
`arm64`. If you wish to use Terraform on a non-`amd64` system, `arm64`. If you wish to use OpenTF on a non-`amd64` system,
[download a normal release `.zip` file](/terraform/downloads) instead. [download a normal release `.zip` file](/opentf/downloads) instead.
## Supported Debian and Ubuntu Releases ## Installing a Specific Version of OpenTF
The HashiCorp APT server contains release repositories for a variety of The OpenTF APT repositories contain multiple versions of OpenTF, but
supported distributions, which are outlined in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide). because the packages are all named `opentf` it is impossible to install
## Installing a Specific Version of Terraform
The HashiCorp APT repositories contain multiple versions of Terraform, but
because the packages are all named `terraform` it is impossible to install
more than one version at a time, and `apt install` will default to selecting more than one version at a time, and `apt install` will default to selecting
the latest version. the latest version.
It's often necessary to match your Terraform version with what a particular It's often necessary to match your OpenTF version with what a particular
configuration is currently expecting. You can use the following command to configuration is currently expecting. You can use the following command to
see which versions are currently available in the repository index: see which versions are currently available in the repository index:
```bash ```bash
apt policy terraform apt policy opentf
``` ```
If your workflow requires using multiple versions of Terraform at the same If your workflow requires using multiple versions of OpenTF at the same
time, for example when working through a gradual upgrade where not all time, for example when working through a gradual upgrade where not all
of your configurations are upgraded yet, we recommend that you use the of your configurations are upgraded yet, we recommend that you use the
official release `.zip` files instead of the APT packages, so you can install official release `.zip` files instead of the APT packages, so you can install
multiple versions at once and then select which to use for each command you multiple versions at once and then select which to use for each command you
run. run.
### Terraform 1.4.3 and Later All published packages include a revision number by
As of Terraform 1.4.3, all published packages include a revision number by
default, starting with `-1`. This change means that in the case that we need default, starting with `-1`. This change means that in the case that we need
to publish an updated package for any reason, installers can automatically to publish an updated package for any reason, installers can automatically
retrieve the latest revision. You can learn more about this packaging change retrieve the latest revision.
in [the announcement](https://discuss.hashicorp.com/t/linux-packaging-debian-revision-change/42403).
You can install the latest revision for a particular version by including the You can install the latest revision for a particular version by including the
version in the `apt install` command, as follows: version in the `apt install` command, as follows:
```bash ```bash
sudo apt install terraform=1.4.4-* sudo apt install opentf=1.4.4-*
```
### Terraform 1.4.2 and Earlier
Terraform 1.4.2 and earlier did not include a revision number for the first
revision, so you can use the following pattern to install a specific version:
```bash
sudo apt install terraform=1.4.0
``` ```

47
website/docs/cli/install/yum.mdx
View File

@ -1,28 +1,21 @@
--- ---
page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux' page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux'
description: >- description: >-
The HashiCorp Yum repositories contain distribution-specific Terraform The OpenTF Yum repositories contain distribution-specific OpenTF
packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems.
--- ---
# Yum/DNF Packages for RHEL, CentOS, and Fedora # Yum/DNF Packages for RHEL, CentOS, and Fedora
The primary distribution packages for Terraform are `.zip` archives containing The primary distribution packages for OpenTF are `.zip` archives containing
single executable files that you can extract anywhere on your system. However, single executable files that you can extract anywhere on your system. However,
for easier integration with configuration management tools and other systematic for easier integration with configuration management tools and other systematic
system configuration strategies, we also offer package repositories for system configuration strategies, we also offer package repositories for
RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to
install Terraform using the `yum install` or `dnf install` commands. install OpenTF using the `yum install` or `dnf install` commands.
If you are instead using Debian or Ubuntu, you If you are instead using Debian or Ubuntu, you
might prefer to [install Terraform from our APT repositories](/terraform/cli/install/apt). might prefer to [install OpenTF from our APT repositories](/opentf/cli/install/apt).
-> **Note:** The Yum repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp
products, rather than just Terraform. Adding these repositories to your
system will, by default, therefore make a number of other non-Terraform
packages available for installation. That might then mask the packages that are
available for some HashiCorp products in the main distribution repositories.
## Repository Configuration ## Repository Configuration
@ -39,7 +32,7 @@ If you are using a Yum-based distribution, add the repository using
```bash ```bash
sudo yum install -y yum-utils sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo sudo yum-config-manager --add-repo https://rpm.releases.placeholderplaceholderplaceholder.com/$release/hashicorp.repo
``` ```
If you are using a DNF-based distribution, add the repository using If you are using a DNF-based distribution, add the repository using
@ -47,27 +40,27 @@ If you are using a DNF-based distribution, add the repository using
```bash ```bash
sudo dnf install -y dnf-plugins-core sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo sudo dnf config-manager --add-repo https://rpm.releases.placeholderplaceholderplaceholder.com/$release/hashicorp.repo
``` ```
In both cases, the Terraform package name is `terraform`. For example: In both cases, the OpenTF package name is `opentf`. For example:
```bash ```bash
yum install terraform yum install opentf
``` ```
## Supported Architectures ## Supported Architectures
The HashiCorp Yum/DNF server has packages only for the `x86_64` The OpenTF Yum/DNF server has packages only for the `x86_64`
architecture, which is also sometimes known as `amd64`. architecture, which is also sometimes known as `amd64`.
There are no official packages available for other architectures, such as There are no official packages available for other architectures, such as
`aarch64`. If you wish to use Terraform on a non-`x86_64` system, `aarch64`. If you wish to use OpenTF on a non-`x86_64` system,
[download a normal release `.zip` file](/terraform/downloads) instead. [download a normal release `.zip` file](/opentf/downloads) instead.
## Supported Distribution Releases ## Supported Distribution Releases
The HashiCorp Yum server contains release repositories for the The OpenTF Yum server contains release repositories for the
following distribution releases: following distribution releases:
* AmazonLinux 2 and "latest" * AmazonLinux 2 and "latest"
@ -85,35 +78,35 @@ any other RPM-based Linux distributions. If you add the repository using
the above commands on other systems then you will see a 404 Not Found error. the above commands on other systems then you will see a 404 Not Found error.
Over time we will change the set of supported distributions, including both Over time we will change the set of supported distributions, including both
adding support for new releases and ceasing to publish new Terraform versions adding support for new releases and ceasing to publish new OpenTF versions
under older releases. under older releases.
## Choosing Terraform Versions ## Choosing OpenTF Versions
The HashiCorp Yum repositories contain multiple versions of Terraform, but The OpenTF Yum repositories contain multiple versions of OpenTF, but
because the packages are all named `terraform` it is impossible to install because the packages are all named `opentf` it is impossible to install
more than one version at a time, and `yum install` or `dnf install` will more than one version at a time, and `yum install` or `dnf install` will
default to selecting the latest version. default to selecting the latest version.
It's often necessary to match your Terraform version with what a particular It's often necessary to match your OpenTF version with what a particular
configuration is currently expecting. Use the following command to configuration is currently expecting. Use the following command to
retrieve the available versions in the repository index: retrieve the available versions in the repository index:
```bash ```bash
yum --showduplicate list terraform yum --showduplicate list opentf
``` ```
You can select a specific version to install by including it in the You can select a specific version to install by including it in the
`yum install` command line, as follows: `yum install` command line, as follows:
```bash ```bash
yum install terraform-0.14.0-2.x86_64 yum install opentf-0.14.0-2.x86_64
``` ```
If you are using a DNF-based distribution, similar use `dnf` instead of `yum` If you are using a DNF-based distribution, similar use `dnf` instead of `yum`
when following the above steps. when following the above steps.
If your workflow requires using multiple versions of Terraform at the same If your workflow requires using multiple versions of OpenTF at the same
time, for example when working through a gradual upgrade where not all time, for example when working through a gradual upgrade where not all
of your configurations are upgraded yet, we recommend that you use the of your configurations are upgraded yet, we recommend that you use the
official release `.zip` files instead of the Yum packages, so you can install official release `.zip` files instead of the Yum packages, so you can install

40
website/docs/cli/plugins/index.mdx
View File

@ -1,5 +1,5 @@
--- ---
page_title: Managing Plugins - Terraform CLI page_title: Managing Plugins - OpenTF CLI
description: >- description: >-
Commands to install, configure, and show information about providers. Also Commands to install, configure, and show information about providers. Also
commands to reduce install effort in air-gapped environments. commands to reduce install effort in air-gapped environments.
@ -7,53 +7,53 @@ description: >-
# Managing Plugins # Managing Plugins
Terraform relies on plugins called "providers" in order to manage various types OpenTF relies on plugins called "providers" in order to manage various types
of resources. (For more information about providers, see of resources. (For more information about providers, see
[Providers](/terraform/language/providers) in the Terraform [Providers](/opentf/language/providers) in the OpenTF
language docs.) language docs.)
-> **Note:** Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but -> **Note:** Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but
we discourage their use. we discourage their use.
Terraform downloads and/or installs any providers OpenTF downloads and/or installs any providers
[required](/terraform/language/providers/requirements) by a configuration [required](/opentf/language/providers/requirements) by a configuration
when [initializing](/terraform/cli/init) a working directory. By default, when [initializing](/opentf/cli/init) a working directory. By default,
this works without any additional interaction but requires network access to this works without any additional interaction but requires network access to
download providers from their source registry. download providers from their source registry.
You can configure Terraform's provider installation behavior to limit or skip You can configure OpenTF's provider installation behavior to limit or skip
network access, and to enable use of providers that aren't available via a network access, and to enable use of providers that aren't available via a
networked source. Terraform also includes some commands to show information networked source. OpenTF also includes some commands to show information
about providers and to reduce the effort of installing providers in airgapped about providers and to reduce the effort of installing providers in airgapped
environments. environments.
## Configuring Plugin Installation ## Configuring Plugin Installation
Terraform's configuration file includes options for caching downloaded plugins, OpenTF's configuration file includes options for caching downloaded plugins,
or explicitly specifying a local or HTTPS mirror to install plugins from. For or explicitly specifying a local or HTTPS mirror to install plugins from. For
more information, see [CLI Config File](/terraform/cli/config/config-file). more information, see [CLI Config File](/opentf/cli/config/config-file).
## Getting Plugin Information ## Getting Plugin Information
Use the [`terraform providers`](/terraform/cli/commands/providers) command to get information Use the [`opentf providers`](/opentf/cli/commands/providers) command to get information
about the providers required by the current working directory's configuration. about the providers required by the current working directory's configuration.
Use the [`terraform version`](/terraform/cli/commands/version) command (or Use the [`opentf version`](/opentf/cli/commands/version) command (or
`terraform -version`) to show the specific provider versions installed for the `opentf -version`) to show the specific provider versions installed for the
current working directory. current working directory.
Use the [`terraform providers schema`](/terraform/cli/commands/providers/schema) command to Use the [`opentf providers schema`](/opentf/cli/commands/providers/schema) command to
get machine-readable information about the resources and configuration options get machine-readable information about the resources and configuration options
offered by each provider. offered by each provider.
## Managing Plugin Installation ## Managing Plugin Installation
Use the [`terraform providers mirror`](/terraform/cli/commands/providers/mirror) command to Use the [`opentf providers mirror`](/opentf/cli/commands/providers/mirror) command to
download local copies of every provider required by the current working download local copies of every provider required by the current working
directory's configuration. This directory will use the nested directory layout directory's configuration. This directory will use the nested directory layout
that Terraform expects when installing plugins from a local source, so you can that OpenTF expects when installing plugins from a local source, so you can
transfer it directly to an airgapped system that runs Terraform. transfer it directly to an airgapped system that runs OpenTF.
Use the [`terraform providers lock`](/terraform/cli/commands/providers/lock) command Use the [`opentf providers lock`](/opentf/cli/commands/providers/lock) command
to update the lock file that Terraform uses to ensure predictable runs when to update the lock file that OpenTF uses to ensure predictable runs when
using ambiguous provider version constraints. using ambiguous provider version constraints.

10
website/docs/cli/plugins/signing.mdx
View File

@ -1,7 +1,7 @@
--- ---
page_title: Plugin Signing page_title: Plugin Signing
description: >- description: >-
Learn about the types of signatures providers can have on the Terraform Learn about the types of signatures providers can have on the OpenTF
Registry. Registry.
--- ---
@ -9,19 +9,19 @@ description: >-
# Plugin Signing # Plugin Signing
~> **Note** Terraform only authenticates provider plugins fetched from a registry. ~> **Note** OpenTF only authenticates provider plugins fetched from a registry.
Terraform providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications: OpenTF providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications:
* **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. * **Signed by HashiCorp** - are built, signed, and supported by HashiCorp.
* **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has * **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has
verified the ownership of the private key and we provide a chain of trust to the CLI to verify this verified the ownership of the private key and we provide a chain of trust to the CLI to verify this
programatically. programatically.
* **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a * **Self-signed** - are built, signed, and supported by a third party. OpenTF does not provide a
verification or chain of trust for the signature. You may obtain and validate fingerprints manually verification or chain of trust for the signature. You may obtain and validate fingerprints manually
if you want to ensure you are using a binary you can trust. if you want to ensure you are using a binary you can trust.
Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install OpenTF does **NOT** support fetching and using unsigned binaries, but you can manually install
unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed. unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed.
Usage of plugins from the registry is subject to the Registry's [Terms of Use](https://registry.terraform.io/terms). Usage of plugins from the registry is subject to the Registry's [Terms of Use](https://registry.terraform.io/terms).

44
website/docs/cli/run/index.mdx
View File

@ -1,27 +1,27 @@
--- ---
page_title: Provisioning Infrastructure - Terraform CLI page_title: Provisioning Infrastructure - OpenTF CLI
description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.'
--- ---
# Provisioning Infrastructure with Terraform # Provisioning Infrastructure with OpenTF
Terraform's primary function is to create, modify, and destroy infrastructure OpenTF's primary function is to create, modify, and destroy infrastructure
resources to match the desired state described in a resources to match the desired state described in a
[Terraform configuration](/terraform/language). [OpenTF configuration](/opentf/language).
When people refer to "running Terraform," they generally mean performing these When people refer to "running OpenTF," they generally mean performing these
provisioning actions in order to affect real infrastructure objects. The provisioning actions in order to affect real infrastructure objects. The
Terraform binary has many other subcommands for a wide variety of administrative OpenTF binary has many other subcommands for a wide variety of administrative
actions, but these basic provisioning tasks are the core of Terraform. actions, but these basic provisioning tasks are the core of OpenTF.
Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and OpenTF's provisioning workflow relies on three commands: `plan`, `apply`, and
`destroy`. All of these commands require an `destroy`. All of these commands require an
[initialized](/terraform/cli/init) working directory, and all of them act [initialized](/opentf/cli/init) working directory, and all of them act
only upon the currently selected [workspace](/terraform/cli/workspaces). only upon the currently selected [workspace](/opentf/cli/workspaces).
## Planning ## Planning
The `terraform plan` command evaluates a Terraform configuration to determine The `opentf plan` command evaluates a OpenTF configuration to determine
the desired state of all the resources it declares, then compares that desired the desired state of all the resources it declares, then compares that desired
state to the real infrastructure objects being managed with the current working state to the real infrastructure objects being managed with the current working
directory and workspace. It uses state data to determine which real objects directory and workspace. It uses state data to determine which real objects
@ -29,38 +29,38 @@ correspond to which declared resources, and checks the current state of each
resource using the relevant infrastructure provider's API. resource using the relevant infrastructure provider's API.
Once it has determined the difference between the current state and the desired Once it has determined the difference between the current state and the desired
state, `terraform plan` presents a description of the changes necessary to state, `opentf plan` presents a description of the changes necessary to
achieve the desired state. It _does not_ perform any actual changes to real achieve the desired state. It _does not_ perform any actual changes to real
world infrastructure objects; it only presents a plan for making changes. world infrastructure objects; it only presents a plan for making changes.
Plans are usually run to validate configuration changes and confirm that the Plans are usually run to validate configuration changes and confirm that the
resulting actions are as expected. However, `terraform plan` can also save its resulting actions are as expected. However, `opentf plan` can also save its
plan as a runnable artifact, which `terraform apply` can use to carry out those plan as a runnable artifact, which `opentf apply` can use to carry out those
exact changes. exact changes.
For details, see [the `terraform plan` command](/terraform/cli/commands/plan). For details, see [the `opentf plan` command](/opentf/cli/commands/plan).
## Applying ## Applying
The `terraform apply` command performs a plan just like `terraform plan` does, The `opentf apply` command performs a plan just like `opentf plan` does,
but then actually carries out the planned changes to each resource using the but then actually carries out the planned changes to each resource using the
relevant infrastructure provider's API. It asks for confirmation from the user relevant infrastructure provider's API. It asks for confirmation from the user
before making any changes, unless it was explicitly told to skip approval. before making any changes, unless it was explicitly told to skip approval.
By default, `terraform apply` performs a fresh plan right before applying By default, `opentf apply` performs a fresh plan right before applying
changes, and displays the plan to the user when asking for confirmation. changes, and displays the plan to the user when asking for confirmation.
However, it can also accept a plan file produced by `terraform plan` in lieu of However, it can also accept a plan file produced by `opentf plan` in lieu of
running a new plan. You can use this to reliably perform an exact set of running a new plan. You can use this to reliably perform an exact set of
pre-approved changes, even if the configuration or the state of the real pre-approved changes, even if the configuration or the state of the real
infrastructure has changed in the minutes since the original plan was created. infrastructure has changed in the minutes since the original plan was created.
For details, see [the `terraform apply` command](/terraform/cli/commands/apply). For details, see [the `opentf apply` command](/opentf/cli/commands/apply).
## Destroying ## Destroying
The `terraform destroy` command destroys all of the resources being managed by The `opentf destroy` command destroys all of the resources being managed by
the current working directory and workspace, using state data to determine which the current working directory and workspace, using state data to determine which
real world objects correspond to managed resources. Like `terraform apply`, it real world objects correspond to managed resources. Like `opentf apply`, it
asks for confirmation before proceeding. asks for confirmation before proceeding.
A destroy behaves exactly like deleting every resource from the configuration A destroy behaves exactly like deleting every resource from the configuration
@ -68,4 +68,4 @@ and then running an apply, except that it doesn't require editing the
configuration. This is more convenient if you intend to provision similar configuration. This is more convenient if you intend to provision similar
resources at a later date. resources at a later date.
For details, see [the `terraform destroy` command](/terraform/cli/commands/destroy). For details, see [the `opentf destroy` command](/opentf/cli/commands/destroy).

26
website/docs/cli/state/index.mdx
View File

@ -1,34 +1,32 @@
--- ---
page_title: Manipulating State - Terraform CLI page_title: Manipulating State - OpenTF CLI
description: >- description: >-
State data tracks which real-world object corresponds to each resource. State data tracks which real-world object corresponds to each resource.
Inspect state, move or import resources, and more. Inspect state, move or import resources, and more.
--- ---
# Manipulating Terraform State # Manipulating OpenTF State
> **Hands-on:** Try the [Manage Resources in Terraform State](/terraform/tutorials/state/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. OpenTF uses [state data](/opentf/language/state) to remember which
Terraform uses [state data](/terraform/language/state) to remember which
real-world object corresponds to each resource in the configuration; real-world object corresponds to each resource in the configuration;
this allows it to modify an existing object when its resource declaration this allows it to modify an existing object when its resource declaration
changes. changes.
Terraform updates state automatically during plans and applies. However, it's OpenTF updates state automatically during plans and applies. However, it's
sometimes necessary to make deliberate adjustments to Terraform's state data, sometimes necessary to make deliberate adjustments to OpenTF's state data,
usually to compensate for changes to the configuration or the real managed usually to compensate for changes to the configuration or the real managed
infrastructure. infrastructure.
Terraform CLI supports several workflows for interacting with state: OpenTF CLI supports several workflows for interacting with state:
- [Inspecting State](/terraform/cli/state/inspect) - [Inspecting State](/opentf/cli/state/inspect)
- [Forcing Re-creation](/terraform/cli/state/taint) - [Forcing Re-creation](/opentf/cli/state/taint)
- [Moving Resources](/terraform/cli/state/move) - [Moving Resources](/opentf/cli/state/move)
- Importing Pre-existing Resources (documented in the - Importing Pre-existing Resources (documented in the
[Importing Infrastructure](/terraform/cli/import) section) [Importing Infrastructure](/opentf/cli/import) section)
- [Disaster Recovery](/terraform/cli/state/recover) - [Disaster Recovery](/opentf/cli/state/recover)
~> **Important:** Modifying state data outside a normal plan or apply can cause ~> **Important:** Modifying state data outside a normal plan or apply can cause
Terraform to lose track of managed resources, which might waste money, annoy OpenTF to lose track of managed resources, which might waste money, annoy
your colleagues, or even compromise the security of your operations. Make sure your colleagues, or even compromise the security of your operations. Make sure
to keep backups of your state data when modifying state out-of-band. to keep backups of your state data when modifying state out-of-band.

12
website/docs/cli/state/inspect.mdx
View File

@ -1,21 +1,21 @@
--- ---
page_title: Inspecting State - Terraform CLI page_title: Inspecting State - OpenTF CLI
description: Commands that allow you to read and update state. description: Commands that allow you to read and update state.
--- ---
# Inspecting State # Inspecting State
Terraform includes some commands for reading and updating state without taking OpenTF includes some commands for reading and updating state without taking
any other actions. any other actions.
- [The `terraform state list` command](/terraform/cli/commands/state/list) - [The `opentf state list` command](/opentf/cli/commands/state/list)
shows the resource addresses for every resource Terraform knows about in a shows the resource addresses for every resource OpenTF knows about in a
configuration, optionally filtered by partial resource address. configuration, optionally filtered by partial resource address.
- [The `terraform state show` command](/terraform/cli/commands/state/show) - [The `opentf state show` command](/opentf/cli/commands/state/show)
displays detailed state data about one resource. displays detailed state data about one resource.
- [The `terraform refresh` command](/terraform/cli/commands/refresh) updates - [The `opentf refresh` command](/opentf/cli/commands/refresh) updates
state data to match the real-world condition of the managed resources. This is state data to match the real-world condition of the managed resources. This is
done automatically during plans and applies, but not when interacting with done automatically during plans and applies, but not when interacting with
state directly. state directly.

32
website/docs/cli/state/move.mdx
View File

@ -1,5 +1,5 @@
--- ---
page_title: Moving Resources - Terraform CLI page_title: Moving Resources - OpenTF CLI
description: >- description: >-
Commands that allow you to manage the way that resources are tracked in state. Commands that allow you to manage the way that resources are tracked in state.
They are helpful when you move or change resources. They are helpful when you move or change resources.
@ -7,41 +7,39 @@ description: >-
# Moving Resources # Moving Resources
Terraform's state associates each real-world object with a configured resource OpenTF's state associates each real-world object with a configured resource
at a specific [resource address](/terraform/cli/state/resource-addressing). This at a specific [resource address](/opentf/cli/state/resource-addressing). This
is seamless when changing a resource's attributes, but Terraform will lose track is seamless when changing a resource's attributes, but OpenTF will lose track
of a resource if you change its name, move it to a different module, or change of a resource if you change its name, move it to a different module, or change
its provider. its provider.
Usually that's fine: Terraform will destroy the old resource, replace it with a Usually that's fine: OpenTF will destroy the old resource, replace it with a
new one (using the new resource address), and update any resources that rely on new one (using the new resource address), and update any resources that rely on
its attributes. its attributes.
In cases where it's important to preserve an existing infrastructure object, you In cases where it's important to preserve an existing infrastructure object, you
can explicitly tell Terraform to associate it with a different configured can explicitly tell OpenTF to associate it with a different configured
resource. resource.
For most cases we recommend using For most cases we recommend using
[the Terraform language's refactoring features](/terraform/language/modules/develop/refactoring) [the OpenTF language's refactoring features](/opentf/language/modules/develop/refactoring)
to document in your module exactly how the resource names have changed over to document in your module exactly how the resource names have changed over
time. Terraform reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps. time. OpenTF reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps.
> **Hands On:** Try the [Use Configuration to Move Resources](/terraform/tutorials/configuration-language/move-config) tutorial.
There are some other situations which require explicit state modifications, There are some other situations which require explicit state modifications,
though. For those, consider the following Terraform commands: though. For those, consider the following OpenTF commands:
- [The `terraform state mv` command](/terraform/cli/commands/state/mv) changes - [The `opentf state mv` command](/opentf/cli/commands/state/mv) changes
which resource address in your configuration is associated with a particular which resource address in your configuration is associated with a particular
real-world object. Use this to preserve an object when renaming a resource, or real-world object. Use this to preserve an object when renaming a resource, or
when moving a resource into or out of a child module. when moving a resource into or out of a child module.
- [The `terraform state rm` command](/terraform/cli/commands/state/rm) tells - [The `opentf state rm` command](/opentf/cli/commands/state/rm) tells
Terraform to stop managing a resource as part of the current working directory OpenTF to stop managing a resource as part of the current working directory
and workspace, _without_ destroying the corresponding real-world object. (You and workspace, _without_ destroying the corresponding real-world object. (You
can later use `terraform import` to start managing that resource in a can later use `opentf import` to start managing that resource in a
different workspace or a different Terraform configuration.) different workspace or a different OpenTF configuration.)
- [The `terraform state replace-provider` command](/terraform/cli/commands/state/replace-provider) - [The `opentf state replace-provider` command](/opentf/cli/commands/state/replace-provider)
transfers existing resources to a new provider without requiring them to be transfers existing resources to a new provider without requiring them to be
re-created. re-created.

14
website/docs/cli/state/recover.mdx
View File

@ -1,7 +1,7 @@
--- ---
page_title: Recovering from State Disasters - Terraform CLI page_title: Recovering from State Disasters - OpenTF CLI
description: >- description: >-
Learn how to restore state backups and override Terraform state protections to fix state errors with the Terraform CLI. Learn how to restore state backups and override OpenTF state protections to fix state errors with the OpenTF CLI.
--- ---
@ -11,15 +11,15 @@ If something has gone horribly wrong (possibly due to accidents when performing
other state manipulation actions), you might need to take drastic actions with other state manipulation actions), you might need to take drastic actions with
your state data. your state data.
- [The `terraform force-unlock` command](/terraform/cli/commands/force-unlock) can - [The `opentf force-unlock` command](/opentf/cli/commands/force-unlock) can
override the protections Terraform uses to prevent two processes from override the protections OpenTF uses to prevent two processes from
modifying state at the same time. You might need this if a Terraform process modifying state at the same time. You might need this if a OpenTF process
(like a normal apply) is unexpectedly terminated (like by the complete (like a normal apply) is unexpectedly terminated (like by the complete
destruction of the VM it's running in) before it can release its lock on the destruction of the VM it's running in) before it can release its lock on the
state backend. Do not run this until you are completely certain what happened state backend. Do not run this until you are completely certain what happened
to the process that caused the lock to get stuck. to the process that caused the lock to get stuck.
- [The `terraform state pull` command](/terraform/cli/commands/state/pull) and - [The `opentf state pull` command](/opentf/cli/commands/state/pull) and
[the `terraform state push` command](/terraform/cli/commands/state/push) can [the `opentf state push` command](/opentf/cli/commands/state/push) can
directly read and write entire state files from and to the configured backend. directly read and write entire state files from and to the configured backend.
You might need this for obtaining or restoring a state backup. You might need this for obtaining or restoring a state backup.

16
website/docs/cli/state/resource-addressing.mdx
View File

@ -16,7 +16,7 @@ An address is made up of two parts:
[module path][resource spec] [module path][resource spec]
``` ```
In some contexts Terraform might allow for an incomplete resource address that In some contexts OpenTF might allow for an incomplete resource address that
only refers to a module as a whole, or that omits the index for a only refers to a module as a whole, or that omits the index for a
multi-instance resource. In those cases, the meaning depends on the context, multi-instance resource. In those cases, the meaning depends on the context,
so you'll need to refer to the documentation for the specific feature you so you'll need to refer to the documentation for the specific feature you
@ -50,9 +50,6 @@ An example of the `module` keyword delineating between two modules that have mul
module.foo[0].module.bar["a"] module.foo[0].module.bar["a"]
``` ```
-> Module index only applies to modules in Terraform v0.13 or later. In earlier
versions of Terraform, a module could not have multiple instances.
## Resource spec ## Resource spec
A resource spec addresses a specific resource instance in the selected module. A resource spec addresses a specific resource instance in the selected module.
@ -68,10 +65,7 @@ resource_type.resource_name[instance index]
to select an instance from a resource that has multiple instances, to select an instance from a resource that has multiple instances,
surrounded by square bracket characters (`[` and `]`). surrounded by square bracket characters (`[` and `]`).
-> In Terraform v0.12 and later, a resource spec without a module path prefix A resource spec without a module path prefix matches only resources in the root module.
matches only resources in the root module. In earlier versions, a resource spec
without a module path prefix would match resources with the same type and name
in any descendent module.
## Index values for Modules and Resources ## Index values for Modules and Resources
@ -88,7 +82,7 @@ The following specifications apply to index values on modules and resources with
### count Example ### count Example
Given a Terraform config that includes: Given a OpenTF config that includes:
```hcl ```hcl
resource "aws_instance" "web" { resource "aws_instance" "web" {
@ -113,13 +107,13 @@ Refers to all four "web" instances.
### for_each Example ### for_each Example
Given a Terraform config that includes: Given a OpenTF config that includes:
```hcl ```hcl
resource "aws_instance" "web" { resource "aws_instance" "web" {
# ... # ...
for_each = { for_each = {
"terraform": "value1", "opentf": "value1",
"resource": "value2", "resource": "value2",
"indexing": "value3", "indexing": "value3",
"example": "value4", "example": "value4",

38
website/docs/cli/state/taint.mdx
View File

@ -1,28 +1,28 @@
--- ---
page_title: Forcing Re-creation of Resources - Terraform CLI page_title: Forcing Re-creation of Resources - OpenTF CLI
description: Commands that allow you to destroy and re-create resources manually. description: Commands that allow you to destroy and re-create resources manually.
--- ---
# Forcing Re-creation of Resources # Forcing Re-creation of Resources
During planning, by default Terraform retrieves the latest state of each During planning, by default OpenTF retrieves the latest state of each
existing object and compares it with the current configuration, planning existing object and compares it with the current configuration, planning
actions only against objects whose current state does not match the actions only against objects whose current state does not match the
configuration. configuration.
However, in some cases a remote object may become damaged or degraded in a However, in some cases a remote object may become damaged or degraded in a
way that Terraform cannot automatically detect. For example, if software way that OpenTF cannot automatically detect. For example, if software
running inside a virtual machine crashes but the virtual machine itself is running inside a virtual machine crashes but the virtual machine itself is
still running then Terraform will typically have no way to detect and respond still running then OpenTF will typically have no way to detect and respond
to the problem, because Terraform only directly manages the machine as a whole. to the problem, because OpenTF only directly manages the machine as a whole.
If you know that an object is damaged, or if you want to force Terraform to If you know that an object is damaged, or if you want to force OpenTF to
replace it for any other reason, you can override Terraform's default behavior replace it for any other reason, you can override OpenTF's default behavior
using [the `-replace=...` planning option](/terraform/cli/commands/plan#replace-address) using [the `-replace=...` planning option](/opentf/cli/commands/plan#replace-address)
when you run either `terraform plan` or `terraform apply`: when you run either `opentf plan` or `opentf apply`:
```shellsession ```shellsession
$ terraform apply -replace="aws_instance.example" $ opentf apply -replace="aws_instance.example"
# ... # ...
# aws_instance.example will be replaced, as requested # aws_instance.example will be replaced, as requested
@ -33,13 +33,13 @@ $ terraform apply -replace="aws_instance.example"
## The "tainted" status ## The "tainted" status
Sometimes Terraform is able to infer automatically that an object is in an Sometimes OpenTF is able to infer automatically that an object is in an
incomplete or degraded state. For example, if creation of a complex object incomplete or degraded state. For example, if creation of a complex object
fails in such a way that parts of it already exist in the remote system, or fails in such a way that parts of it already exist in the remote system, or
if object creation succeeded but a provisioner step subsequently failed, if object creation succeeded but a provisioner step subsequently failed,
Terraform must remember that the object exists but may not be fully-functional. OpenTF must remember that the object exists but may not be fully-functional.
Terraform represents this situation by marking an object in the state as OpenTF represents this situation by marking an object in the state as
"tainted". When an object is marked with this status, the next plan will force "tainted". When an object is marked with this status, the next plan will force
replacing that object in a similar way to if you had specified that object's replacing that object in a similar way to if you had specified that object's
address using `-replace=...` as described above. address using `-replace=...` as described above.
@ -51,13 +51,13 @@ address using `-replace=...` as described above.
} }
``` ```
If Terraform has marked an object as tainted but you consider it to be working If OpenTF has marked an object as tainted but you consider it to be working
correctly and do not want to replace it, you can override Terraform's correctly and do not want to replace it, you can override OpenTF's
determination using [the `terraform untaint` command](/terraform/cli/commands/untaint), determination using [the `opentf untaint` command](/opentf/cli/commands/untaint),
after which Terraform will consider the object to be ready for use by any after which OpenTF will consider the object to be ready for use by any
downstream resource declarations. downstream resource declarations.
You can also _force_ Terraform to mark a particular object as tainted using You can also _force_ OpenTF to mark a particular object as tainted using
[the `terraform taint` command](/terraform/cli/commands/taint), but that approach is [the `opentf taint` command](/opentf/cli/commands/taint), but that approach is
deprecated in favor of the `-replace=...` option, which avoids the need to deprecated in favor of the `-replace=...` option, which avoids the need to
create an interim state snapshot with a tainted object. create an interim state snapshot with a tainted object.

47
website/docs/cli/workspaces/index.mdx
View File

@ -1,5 +1,5 @@
--- ---
page_title: Managing Workspaces - Terraform CLI page_title: Managing Workspaces - OpenTF CLI
description: >- description: >-
Commands to list, select, create, and output workspaces. Workspaces help Commands to list, select, create, and output workspaces. Workspaces help
manage different groups of resources with one configuration. manage different groups of resources with one configuration.
@ -7,27 +7,27 @@ description: >-
# Managing Workspaces # Managing Workspaces
Workspaces in the Terraform CLI refer to separate instances of [state data](/terraform/language/state) inside the same Terraform working directory. They are distinctly different from [workspaces in Terraform Cloud](/terraform/cloud-docs/workspaces), which each have their own Terraform configuration and function as separate working directories. Workspaces in the OpenTF CLI refer to separate instances of [state data](/opentf/language/state) inside the same OpenTF working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTF configuration and function as separate working directories.
Terraform relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, Terraform can manage multiple sets of non-overlapping resources. OpenTF relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, OpenTF can manage multiple sets of non-overlapping resources.
Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the Terraform CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls. Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the OpenTF CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls.
## Managing CLI Workspaces ## Managing CLI Workspaces
Every [initialized working directory](/terraform/cli/init) starts with one workspace named `default`. Every [initialized working directory](/opentf/cli/init) starts with one workspace named `default`.
Use the [`terraform workspace list`](/terraform/cli/commands/workspace/list), [`terraform workspace new`](/terraform/cli/commands/workspace/new), and [`terraform workspace delete`](/terraform/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory. Use the [`opentf workspace list`](/opentf/cli/commands/workspace/list), [`opentf workspace new`](/opentf/cli/commands/workspace/new), and [`opentf workspace delete`](/opentf/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory.
Use [the `terraform workspace select` command](/terraform/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most Terraform commands only interact with the currently selected workspace. This includes [provisioning](/terraform/cli/run) and [state manipulation](/terraform/cli/state). Use [the `opentf workspace select` command](/opentf/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTF commands only interact with the currently selected workspace. This includes [provisioning](/opentf/cli/run) and [state manipulation](/opentf/cli/state).
When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/terraform/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/opentf/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region.
## Use Cases ## Use Cases
You can create multiple [working directories](/terraform/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches. You can create multiple [working directories](/opentf/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, OpenTF installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches.
A common use for multiple workspaces is to create a parallel, distinct copy of A common use for multiple workspaces is to create a parallel, distinct copy of
a set of infrastructure to test a set of changes before modifying production infrastructure. a set of infrastructure to test a set of changes before modifying production infrastructure.
@ -40,7 +40,7 @@ The default workspace might correspond to the `main` or `trunk` branch, which de
Workspaces let you quickly switch between multiple instances of a **single configuration** within its **single backend**. They are not designed to solve all problems. Workspaces let you quickly switch between multiple instances of a **single configuration** within its **single backend**. They are not designed to solve all problems.
When using Terraform to manage larger systems, you should create separate Terraform configurations that correspond to architectural boundaries within the system. This lets teams manage different components separately. Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend. When using OpenTF to manage larger systems, you should create separate OpenTF configurations that correspond to architectural boundaries within the system. This lets teams manage different components separately. Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend.
In particular, organizations commonly want to create a strong separation In particular, organizations commonly want to create a strong separation
between multiple deployments of the same infrastructure serving different between multiple deployments of the same infrastructure serving different
@ -48,39 +48,26 @@ development stages or different internal teams. In this case, the backend for ea
## Alternatives to Workspaces ## Alternatives to Workspaces
Instead of creating CLI workspaces, you can use one or more [re-usable modules](/terraform/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/terraform/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments. Instead of creating CLI workspaces, you can use one or more [re-usable modules](/opentf/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/opentf/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments.
When multiple configurations represent distinct system components rather than multiple deployments, you can pass data from one component to another using paired resources types and data sources. When multiple configurations represent distinct system components rather than multiple deployments, you can pass data from one component to another using paired resources types and data sources.
- When a shared [Consul](https://www.consul.io/) cluster is available, use [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) to retrieve those values in other configurations. - If you have a configuration management system accessible from all configurations, then one can use a `resource` to export variables, while another configuration can use a `datasource` to import them.
- In systems that support user-defined labels or tags, use a tagging convention to make resources automatically discoverable. For example, use [the `aws_vpc` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) to assign suitable tags and then [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) to query by those tags in other configurations. - In systems that support user-defined labels or tags, use a tagging convention to make resources automatically discoverable. For example, use [the `aws_vpc` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) to assign suitable tags and then [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) to query by those tags in other configurations.
- For server addresses, use a provider-specific resource to create a DNS record with a predictable name. Then you can either use that name directly or use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve the published addresses in other configurations. - For server addresses, use a provider-specific resource to create a DNS record with a predictable name. Then you can either use that name directly or use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve the published addresses in other configurations.
- If you store a Terraform state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/terraform/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system. - If you store a OpenTF state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/opentf/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system.
## Interactions with Terraform Cloud Workspaces
Terraform Cloud organizes infrastructure using workspaces, but its workspaces
act more like completely separate working directories. Each Terraform Cloud
workspace has its own Terraform configuration, set of variable values, state
data, run history, and settings.
When you [integrate Terraform CLI with Terraform Cloud](/terraform/cli/cloud), you can associate the current CLI working directory with one or more remote Terraform Cloud workspaces. Then, use the `terraform workspace` commands to select the remote workspace you want to use for each run.
Refer to [CLI-driven Runs](/terraform/cloud-docs/run/cli) in the Terraform Cloud documentation for more details.
## Workspace Internals ## Workspace Internals
Workspaces are technically equivalent to renaming your state file. Terraform then includes a set of protections and support for remote state. Workspaces are technically equivalent to renaming your state file. OpenTF then includes a set of protections and support for remote state.
Workspaces are also meant to be a shared resource. They are not private, unless you use purely local state and do not commit your state to version control. Workspaces are also meant to be a shared resource. They are not private, unless you use purely local state and do not commit your state to version control.
For local state, Terraform stores the workspace states in a directory called `terraform.tfstate.d`. This directory should be treated similarly to local-only `terraform.tfstate`. Some teams commit these files to version control, but we recommend using a remote backend instead when there are multiple collaborators. For local state, OpenTF stores the workspace states in a directory called `terraform.tfstate.d`. This directory should be treated similarly to local-only `terraform.tfstate`. Some teams commit these files to version control, but we recommend using a remote backend instead when there are multiple collaborators.
For [remote state](/terraform/language/state/remote), the workspaces are stored directly in the configured [backend](/terraform/language/settings/backends/configuration). For example, if you use [Consul](/terraform/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping. For [remote state](/opentf/language/state/remote), the workspaces are stored directly in the configured [backend](/opentf/language/settings/backends/configuration). For example, if you use [Consul](/opentf/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping.
Terraform stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [CLI Integration (recommended)](/terraform/cli/cloud/settings#arguments) and [remote backend](/terraform/language/settings/backends/remote#workspaces) and documentation. OpenTF stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the [CLI Integration (recommended)](/opentf/cli/cloud/settings#arguments) and [remote backend](/opentf/language/settings/backends/remote#workspaces) and documentation.