ENVCRYPT

envcrypt is an encrypt/decrypt CLI tool that was built for the purpose of storing encrypted (AES-256) .env files in version control. By default, envcrpyt will take any .env files and create an encrypted .envcrypt file. The unencrypted .env files should not be committed to version control. The .envcrypt file can be.

Overwrite Protection

To prevent accidentally overwriting changes pulled from version control, envcrypt encrypt includes a safety check. It compares the state of the current .envcrypt file (based on its content hash) with the state recorded when the local .env files were last created (via envcrypt decrypt). If they don't match, it suggests the .envcrypt file might have been updated remotely.

This check uses a local .envcrypt.config file to track the last decrypted state via the last_decrypted_hash property.

If the check fails, you will be prompted to run envcrypt decrypt first to integrate any remote changes into your local .env files before encrypting again. You can bypass this check using the --force flag, but be cautious as this might overwrite changes from others.

Configuration (.envcrypt.config)

You can optionally store your encryption key and manage state within a .envcrypt.config JSON file in your project root. This file should be added to your .gitignore file.

Example .envcrypt.config:
``json
{
"key": "your-super-secret-key",
"last_decrypted_hash": "a1b2c3d4..."
}
`
* key (Optional): If present, envcrypt will use this key instead of prompting. The --key command-line argument still takes precedence.
* last_decrypted_hash (Managed by envcrypt): Stores the hash of the .envcrypt content the last time decrypt was successfully run. Used for the overwrite protection check.

Usage

1. Add @jaketig/envcrypt as a dev dependency
`
npm install @jaketig/envcrypt --save-dev
`

2. Add .envcrypt.config to your .gitignore file.

3. Use the CLI
`
envcrypt
`

Commands

Command	Alias	Description
encrypt	e, enc	Encrypt the contents of .env files. Includes overwrite protection.
decrypt	d, dec	Decrypt the contents of .envcrypt file to original files and update local state.

Options

Option	Alias	Scope	Description
--key		encrypt, decrypt	Encryption key used to encrypt/decrypt contents. Overrides key in .envcrypt.config. Optional, will prompt if not found elsewhere.
--force	-f	encrypt	Force encryption, bypassing the overwrite protection check. Use with caution.

Examples

Bare Minimum Encryption
`
envcrypt e
`
- will prompt for secret key
- will encrypt .env to .envcrypt (if overwrite check passes)




Bare Minimum Decryption
`
envcrypt d
`
- will prompt for secret key
- will decrypt .envcrypt to .env
- will update .envcrypt.config




Pass Key

`
envcrypt d --key=supersecret
`
- will decrypt .envcrypt to .env




Force Encryption (Overwrite)
`
envcrypt e --key=supersecret --force
`
- will encrypt .env to .envcrypt`, ignoring potential state mismatch.