Skip to main content

atmos secret keygen

Generate a new age key pair in-process for a named secrets vault (a secrets.providers.<name> entry backed by SOPS), with no manual age-keygen step. The private identity is written to the vault's key source (its spec.age_key_file, or the SOPS-standard keys file that the default keyservice reads), and the public recipient is recorded in .sops.yaml (or spec.recipients_file). After running it, atmos secret set creates and encrypts the first file with no sops binary required.

atmos secret keygen --help

Usage​

atmos secret keygen [VAULT] [flags]

Use --stack (-s) to resolve providers declared in a stack, and --component (-c) for component overrides. Provider discovery does not require any secret declarations. If a provider differs between components, select a component explicitly. Without a stack, providers come from atmos.yaml.

With no VAULT argument, the single configured SOPS vault is used; if several are configured, name one.

Examples​

# Generate a key for the only configured SOPS vault, then encrypt the first secret
atmos secret keygen
atmos secret set DB_PASSWORD=hunter2 --stack=prod --component=api

# Generate a key for a specific named vault
atmos secret keygen prod-sops

# Generate a key from a stack or component provider
atmos secret keygen local --stack=dev
atmos secret keygen local --stack=dev --component=api --type=terraform

# Generate an additional key even if the vault already has one
atmos secret keygen --force

Key generation is also offered interactively by atmos secret init when a SOPS-backed vault has no key yet.

Where each half lands​

A generated identity has two halves, and keygen writes each to the sink implied by the vault's configuration — there is no --sink flag; the YAML definition is the single source of truth:

Private identity (AGE-SECRET-KEY-1…, decrypts)

Written to the vault's spec.age_key_file when set, otherwise the SOPS-standard keys file (SOPS_AGE_KEY_FILE, or &lt;user config dir&gt;/sops/age/keys.txt) that the default keyservice reads automatically. It is appended, never overwritten — the keys file holds many identities and SOPS tries them all on decrypt, so multiple vaults can share it. Keep this file out of version control.

Public recipient (age1…, encrypts)

Recorded as a creation_rule in .sops.yaml (or spec.recipients_file), whose path_regex is derived from the vault's spec.file. Existing rules and keys are preserved. The recipient only encrypts, so it is safe to commit, and it is printed to stdout so you can share it.

When a private key already exists but the vault has no recipient rule, keygen derives the public recipient and restores the rule without changing the private key. This also works when a second vault shares the same key file. Existing matching rules and explicit spec.age_recipients are preserved.

Recovery requires one distinct age identity in the configured source. If a shared key file contains several identities, point spec.age_key_file to the intended identity or configure spec.age_recipients explicitly; Atmos does not add every key in the file as a recipient. Use --force only when you intend to generate additional private key material.

Inline spec.age_key supports public-recipient recovery, but generating a new private key requires a writable key sink. Vaults with explicit spec.age_recipients remain manually managed.

Sharing the private key​

The public recipient is printed on generation and is safe to share. To export a private key for a teammate or backup, send the keys file directly, or — for a key stored in a keychain store — reveal it with atmos secret get:

atmos secret get SOPS_AGE_KEY --mask=false

Arguments​

VAULT (optional)
The named SOPS vault (a secrets.providers.<name> entry) to generate a key for. Omit it when exactly one SOPS vault is configured.

Flags​

--stack / -s
Resolve providers from this stack, overriding global providers with the same name.
--component / -c
Select a component provider override. Requires --stack.
--type
Restrict component discovery to this component type.
--force / -f
Generate a new key even if the vault already has one (appends an additional identity).