Skip to main content

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.

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 on a fully-scoped (--stack + --component) target.

atmos secret list --help

Usage​

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

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