| --- | |
| description: The `tofu state push` command pushes items to the OpenTofu state. | |
| --- | |
| # Command: state push | |
| The `tofu state push` command is used to manually upload a local | |
| state file to [remote state](../../../language/state/remote.mdx). This command also | |
| works with local state. | |
| This command should rarely be used. It is meant only as a utility in case | |
| manual intervention is necessary with the remote state. | |
| ## Usage | |
| Usage: `tofu state push [options] PATH` | |
| This command pushes the state specified by PATH to the currently | |
| configured [backend](../../../language/settings/backends/configuration.mdx). | |
| 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 | |
| the destination state. | |
| :::note | |
| OpenTofu 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 `tofu state push | sc terraform.tfstate`. | |
| ::: | |
| OpenTofu will perform a number of safety checks to prevent you from | |
| making changes that appear to be unsafe: | |
| - **Differing lineage**: If the "lineage" value in the state differs, | |
| OpenTofu will not allow you to push the state. A differing lineage | |
| suggests that the states are completely different and you may lose | |
| data. | |
| - **Higher remote serial**: If the "serial" value in the destination state | |
| is higher than the state being pushed, OpenTofu will prevent the push. | |
| A higher serial suggests that data is in the destination state that isn't | |
| accounted for in the local state being pushed. | |
| Both of these safety checks can be disabled with the `-force` flag. | |
| **This is not recommended.** If you disable the safety checks and are | |
| pushing state, the destination state will be overwritten. | |
| For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx) | |
| only, `tofu state push` also accepts the option [`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). | |
| :::note | |
| Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation), | |
| [backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals), | |
| or [encryption block](../../../language/state/encryption.mdx#configuration) | |
| requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) | |
| when running `tofu state push`. | |
| ::: | |
| This command also accepts the following options for tofu state push: | |
| - `-lock=false` - Don't hold a state lock during the operation. This is | |
| dangerous if others might concurrently run commands against the same | |
| workspace. | |
| - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, | |
| instructs OpenTofu to retry acquiring a lock for a period of time before | |
| returning an error. The duration syntax is a number followed by a time | |
| unit letter, such as "3s" for three seconds. | |
| - [`ignore-remote-version`](../../../cli/cloud/command-line-arguments.mdx#ignore-remote-version). | |
| - `-var 'NAME=VALUE'` - Sets a value for a single | |
| [input variable](../../../language/values/variables.mdx) declared in the | |
| root module of the configuration. Use this option multiple times to set | |
| more than one variable. Refer to | |
| [Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information. | |
| - `-var-file=FILENAME` - Sets values for potentially many | |
| [input variables](../../../language/values/variables.mdx) declared in the | |
| root module of the configuration, using definitions from a | |
| ["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files). | |
| Use this option multiple times to include values from more than one file. | |
| - `-json` - Enables the [machine readable JSON UI](../../../internals/machine-readable-ui.mdx) output. | |
| - `-json-into=out.json` - Produces the same output as -json, but redirected to a file. This allows | |
| for simultaneous capture of both human readable and machine readable logs. | |
| There are several other ways to set values for input variables in the root | |
| module, aside from the `-var` and `-var-file` options. Refer to | |
| [Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information. |