# 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. `list` **never retrieves or decrypts secret values** and never registers them for masking — it only reports whether each secret is set.

:::tip Credential-free by default
Listing requires **no authenticated identity and never decrypts**. Local backends (e.g. SOPS — whose initialization is determined from the file's cleartext key names) always show an accurate `STATUS`. Remote stores (AWS SSM/Secrets Manager, Azure Key Vault, GCP Secret Manager, Vault, 1Password) would need a credential just to check existence, so their status shows `unknown` unless you pass [`--verify`](#flags) on a fully-scoped (`--stack` + `--component`) target.
:::

## 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.

## Status column

The `STATUS` column reports a backend **existence** check (never a value retrieval or decryption):

- **`initialized`**
  The secret is set in its backend.
- **`missing`**
  The secret is declared but not yet set.
- **`unknown`**
  Not checked — the backend is remote and would require credentials. Pass 
  [`--verify`](#flags)
   on a fully-scoped target to contact the backend for a definitive answer.
- **`error`**
  The status check failed (e.g. access denied) while verifying.

## 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

# Verify remote-store status (contacts the backend with a read identity)
atmos secret list --stack=prod --component=api --verify

# 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
```

By default, listing authenticates nothing: local backends (SOPS) report an accurate status while
remote-store secrets show `unknown`. Use `--verify` with a fully-scoped (`--stack` + `--component`)
target to contact remote backends and resolve their real `initialized`/`missing` status.

## 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`
- **`--verify`**

  Contact remote backends to confirm each secret's initialization status. **Optional, off by default** — listing is credential-free, so remote-store secrets show `unknown` unless this flag is set. Requires a fully-scoped target (`--stack` and `--component`); the read/describe identity is resolved lazily (via `--identity`) and never decrypts the value. Local backends (e.g. SOPS) are always checked regardless of this flag.
- **`--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