# atmos secret list

List declared secrets as a table showing STACK, COMPONENT, SECRET, SCOPE, PROVIDER, and STATUS. `--stack` and `--component` are **facets** (optional filters): with neither, every secret is listed across all stacks; either one narrows the result. The status reflects a backend existence check (`initialized`, `missing`, or `error`), so `list` never retrieves secret values and never registers them for masking.

## Usage

```shell
atmos secret list [flags]
```

## Scope column

The `SCOPE` column shows whether a secret is `stack`-scoped (stored once and shared by every
component instance in the stack) or `instance`-scoped (stored per component). Stack-scoped secrets
appear once with a `*` component, since they are shared. See [Secret scopes](/cli/commands/secret/usage#secret-scopes) for details.

## Examples

```shell
# List ALL secrets across every stack (facets omitted)
atmos secret list

# Narrow by facet
atmos secret list --stack=prod
atmos secret list --component=api

# Fully scoped (fast path, honors --identity)
atmos secret list --stack=prod --component=api

# Include declaration descriptions in the output
atmos secret list --stack=prod --component=api --verbose

# Pipeline-friendly output (no prompt, mask-aware)
atmos secret list --format=json
```

In all-stacks mode, status is resolved best-effort using each component instance's own identity; a
row whose backend can't be reached renders as `error` rather than aborting the listing.

## Arguments

- **n/a**
  No positional arguments.

## Flags

- **`--stack` (alias `-s`)**

  Filter to a single stack. **Optional** — omit to list across all stacks.

  **Environment variable:** `ATMOS_STACK`
- **`--component` (alias `-c`)**

  Filter to a single component. **Optional** — omit to list across all components.

  **Environment variable:** `ATMOS_COMPONENT`
- **`--type`**

  The component type (`terraform`, `helmfile`, `packer`, or `ansible`). Used to disambiguate when a component name exists in more than one type.
- **`--identity` (alias `-i`)**

  The identity to use when accessing the secret backend.

  **Environment variable:** `ATMOS_IDENTITY`
- **`--verbose` (alias `-v`)**

  Include each secret's declaration description in the output.

## See Also

- [atmos secret](/cli/commands/secret/usage) — Overview of the secret command group
- [`!secret` YAML function](/functions/yaml/secret) — Resolve declared secrets at runtime