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

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

Vaults that pin recipients via `spec.age_recipients`, or source an inline key via `spec.age_key`, are managed manually; `keygen` reports this rather than overwriting your configuration.

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

- **`--force` / `-f`**
  Generate a new key even if the vault already has one (appends an additional identity).