# 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.
- **`unresolved`** — The declaration's `store` or `sops` uses a deferred executable or credential-backed function, such as `!exec`, `!starlark`, or `!aws.cloudformation.output`. Without `--verify`, the `PROVIDER` column shows the raw selector and the `REASON` column explains it. Pass [`--verify`](#flags) to resolve the selector and check the secret.
- **`error`** — The status check failed (e.g. access denied) while verifying, or a selector could not be resolved (for example, its producer is not deployed). The `REASON` column, and the `reason` field in `json`/`yaml` output, states why.

A `REASON` column appears only when at least one row has a reason to show. If a component's declarations cannot be evaluated, `list` names that component and stack in a warning and still lists the other components.

## 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` (and selector-backed declarations show `unresolved`) 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