---
description: >-
  The tofu state list command is used to list resources within a OpenTofu
  state.
---

# Command: state list

The `tofu state list` command is used to list resources within a
[OpenTofu state](../../../language/state/index.mdx).

## Usage

Usage: `tofu state list [options] [address...]`

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.

The resources listed are sorted according to module depth order followed
by alphabetical. This means that resources that are in your immediate
configuration are listed first, and resources that are more deeply nested
within modules are listed last.

For complex infrastructures, the state can contain thousands of resources.
To filter these, provide one or more patterns to the command. Patterns are
in [resource addressing format](../../../cli/state/resource-addressing.mdx).

:::note
Use of variables in [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 list`.
:::

The command-line flags are all optional. The following flags are available:

* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
  Ignored when [remote state](../../../language/state/remote.mdx) is used.

* `-id=id` - ID of resources to show. Ignored when unset.

* `-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.

## Example: All Resources

This example will list all resources, including modules:

```
$ tofu state list
aws_instance.foo
aws_instance.bar[0]
aws_instance.bar[1]
module.elb.aws_elb.main
```

## Example: Filtering by Resource

This example will only list resources for the given name:

```
$ tofu state list aws_instance.bar
aws_instance.bar[0]
aws_instance.bar[1]
```

## Example: Filtering by Module

This example will list resources in the given module and any submodules:

```
$ tofu state list module.elb
module.elb.aws_elb.main
module.elb.module.secgroups.aws_security_group.sg
```

## Example: Filtering by ID

This example will only list the resource whose ID is specified on the
command line. This is useful to find where in your configuration a
specific resource is located.

```
$ tofu state list -id=sg-1234abcd
module.elb.aws_security_group.sg
```
