> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTofu State Commands
> This article explains how to manage the OpenTofu state file using various commands for safe resource handling.
Managing the OpenTofu state file directly is error-prone. Instead, use the `tofu state` subcommands to list, inspect, rename, pull, remove, and push resources safely.
| Command | Description |
| ------------ | ------------------------------------------------------ |
| `state show` | Display detailed attributes of a resource in state |
| `state list` | List all resource addresses or filter by pattern |
| `state mv` | Rename or move resources within or between state files |
| `state pull` | Download remote state to your local machine |
| `state rm` | Remove a resource from the state without destroying it |
| `state push` | Overwrite remote state with a local state file |
## Viewing Resource Attributes with `state show`
To inspect resource attributes in the state file:
```bash theme={null}
tofu state show aws_s3_bucket.finance
```
Example (truncated):
```json theme={null}
{
"mode": "managed",
"type": "aws_s3_bucket",
"name": "finance",
"provider": "provider[\"registry.opentofu.org/hashicorp/aws\"]",
"instances": [
{
"attributes": {
"bucket": "finance",
"arn": "arn:aws:s3:::finance",
"region": "us-west-2",
"tags": {
"Environment": "Production"
},
"versioning": [
{
"enabled": false,
"mfa_delete": false
}
]
}
}
]
}
```
## Listing Resources with `state list`
Show all resource addresses in your state:
```bash theme={null}
tofu state list
```
Sample output:
```text theme={null}
aws_dynamodb_table.cars
aws_s3_bucket.finance-2020922
```
Filter by a resource pattern:
```bash theme={null}
tofu state list aws_s3_bucket.cerberus-finance
# aws_s3_bucket.cerberus-finance
```
## Renaming Resources with `state mv`
Rename a resource address in your state file (or move it between state files).
1. Initial Terraform configuration (`main.tf`):
```hcl theme={null}
resource "aws_dynamodb_table" "state-locking" {
name = "state-locking"
billing_mode = "PAY_PER_REQUEST"
hash_key = "LockID"
attribute {
name = "LockID"
type = "S"
}
}
```
2. Existing state snapshot:
```json theme={null}
{
"resources": [
{
"mode": "managed",
"type": "aws_dynamodb_table",
"name": "state-locking",
"provider": "provider[\"registry.opentofu.org/hashicorp/aws\"]"
}
]
}
```
3. Rename in state:
```bash theme={null}
tofu state mv \
aws_dynamodb_table.state-locking \
aws_dynamodb_table.state-locking-db
Move "aws_dynamodb_table.state-locking" to "aws_dynamodb_table.state-locking-db"
Successfully moved 1 object(s).
```
4. Update configuration:
```hcl theme={null}
resource "aws_dynamodb_table" "state-locking-db" {
name = "state-locking"
billing_mode = "PAY_PER_REQUEST"
hash_key = "LockID"
attribute {
name = "LockID"
type = "S"
}
}
```
5. Verify no pending changes:
```bash theme={null}
tofu apply
# Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
```
## Downloading Remote State with `state pull`
Fetch and view your remote state locally:
```bash theme={null}
tofu state pull
```
Example:
```json theme={null}
{
"version": 4,
"terraform_version": "1.6.1",
"serial": 0,
"lineage": "b6e2cf0e...",
"resources": [
{
"mode": "managed",
"type": "aws_dynamodb_table",
"name": "state-locking-db",
"provider": "provider[\"registry.opentofu.org/hashicorp/aws\"]",
"instances": [
{
"attributes": {
"hash_key": "LockID",
"billing_mode": "PAY_PER_REQUEST"
...
}
}
]
}
]
}
```
You can pipe into [jq](https://stedolan.github.io/jq/) to filter:
```bash theme={null}
tofu state pull \
| jq '.resources[]
| select(.name=="state-locking-db")
| .instances[].attributes.hash_key'
# "LockID"
```
## Removing Resources from State with `state rm`
When you need Terraform/OpenTofu to stop managing a resource—but keep it running in the cloud—use:
```bash theme={null}
tofu state rm aws_s3_bucket.finance-2020922
```
Sample output:
```text theme={null}
Acquiring state lock. This may take a few moments...
Removed aws_s3_bucket.finance-2020922
Successfully removed 1 resource instance(s).
Releasing state lock. This may take a few moments...
```
`state rm` only removes the resource from the Terraform/OpenTofu state—it does **not** delete the actual resource in your cloud provider.
After removing, delete the corresponding `resource` block in your configuration.
## Overwriting Remote State with `state push`
Use this command to replace the remote state with a local file. OpenTofu will refuse if the lineages don’t match:
```bash theme={null}
tofu state push ./randomstate/terraform.tfstate
# Failed to write state: cannot import state with lineage "1dc19ee8-..." over unrelated state with lineage "6d167ba6-..."
```
To force an overwrite (use with extreme caution):
```bash theme={null}
tofu state push --force ./randomstate/terraform.tfstate
```
Forcing a push can irreversibly corrupt your remote state. Always back up your existing state before using `--force`.
***
## Links and References
* [OpenTofu Documentation](https://docs.opentofu.org/)
* [jq – JSON processor](https://stedolan.github.io/jq/)
* [Terraform State Commands](https://developer.hashicorp.com/terraform/cli/commands/state)