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

## Usage

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

```shell
# 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`](/cli/commands/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`](/cli/commands/secret/get):

```shell
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).