Create & Edit Secrets¶

Use secret edit to create or update an age-encrypted dotenv bundle. Configure an age identity, then pass the bundle path:

export DOTENV_FUSION_AGE_IDENTITY=/home/user/.config/age/keys.txt
dotenv-fusion secret edit secrets/application.env.age

An existing bundle is decrypted for editing. A new bundle opens as an empty dotenv document. Store ordinary NAME=value assignments:

DATABASE_USERNAME=application
DATABASE_PASSWORD='literal $value # with spaces'

Bundle values are literal. They do not expand variables and do not support #@ directives. Declare selectors separately in .env-fuse, then validate the application configuration:

#@def DATABASE_USERNAME source="age://store/application.env.age#DATABASE_USERNAME"
#@def DATABASE_PASSWORD required=true source="age://store/application.env.age#DATABASE_PASSWORD"

dotenv-fusion check -f .env-fuse

Select the editor¶

The editor is selected from --editor, VISUAL, or EDITOR, in that order. Without a configured editor, dotenv-fusion tries Nano and then Vim with their persistent backup and history features disabled.

dotenv-fusion secret edit secrets/application.env.age \
  --editor 'nano --ignorercfiles'

The editor command is parsed as arguments and executed without a shell.

Select encryption recipients¶

In the common single-key case, dotenv-fusion derives the public recipient from the configured native age identity. An explicit recipient is unnecessary.

Existing single-recipient X25519 bundles support automatic recipient inference. An identity that decrypts a multi-recipient bundle cannot recover the complete recipient list, so those bundles require every intended recipient explicitly.

For a new bundle intended for another person, or for bundles with several recipients, provide the complete recipient set:

dotenv-fusion secret edit secrets/shared.env.age \
  --age-recipients-file config/age-recipients.txt

--age-recipient and --age-recipients-file are repeatable. Explicit options replace inferred recipients, so include every recipient that must retain access. They also allow creating a bundle for someone else's public key without holding their identity.

When recipients are inferred from an identity, dotenv-fusion verifies the new ciphertext by decrypting it and comparing the edited bytes. With explicit recipients, successful age encryption is used because their private identities may not be available locally.

Saving and recovery¶

• Unchanged or empty content leaves the bundle untouched.
• Invalid dotenv content, editor failure, or encryption failure leaves the original bundle unchanged.
• Before replacing an existing bundle, dotenv-fusion flushes a unique encrypted backup of the exact original bytes beside it and prints the backup path.
• A .NAME.lock file prevents concurrent edits by this command. Remove a stale lock only after confirming that no edit is still running.
• The new ciphertext is written separately, flushed, and installed atomically.
• On POSIX, the bundle, backup, and temporary plaintext file use mode 0600; the temporary directory uses mode 0700.
• Ctrl+C and handled termination signals clean up the temporary workspace. Editor failures cancel the save.

Editing requires a plaintext temporary file. dotenv-fusion prefers /dev/shm when it is available and writable, otherwise it uses the system temporary directory. Use --temp-dir to select the location explicitly. Configure custom editors so they do not create backups, histories, or synchronized copies.

See Security & Limitations for the remaining storage and process boundaries.