envcipher 0.1.3

Secure .env file encryption using OS keychain. Keep secrets encrypted at rest.

Envcipher

Encrypt .env files using AES-256-GCM with keys stored in your OS keychain. Decrypt on demand for local development without managing separate key files.

---

Installation

Python

pip install envcipher

Provides both the CLI and Python library.

Rust

cargo install envcipher

CLI only.

From Source

git clone https://github.com/iamprecieee/envcipher
cd envcipher
cargo install --path .

---

Usage

CLI

envcipher init          # Generate key, store in OS keychain
envcipher edit          # Decrypt -> edit -> re-encrypt
envcipher lock          # Encrypt .env in place
envcipher unlock        # Decrypt .env to plaintext
envcipher run -- <cmd>  # Run command with decrypted env vars
envcipher status        # Show encryption status

Python Library

import envcipher
import os

# Load encrypted .env into os.environ
envcipher.load()

# Access secrets
api_key = os.getenv("API_KEY")

Custom path:

envcipher.load(path="/path/to/.env")

Works with both encrypted and plaintext files.

---

Team Sharing

# Export key
envcipher export-key
# Output: qQWntX6r7eANxsyKHbkJtuXtzW0Hy5zjJGvDSxMKM9I=

# Import on another machine
envcipher import-key qQWntX6r7eANxsyKHbkJtuXtzW0Hy5zjJGvDSxMKM9I=

Share keys through secure channels only.

---

Security

Component	Implementation
Encryption	AES-256-GCM, 96-bit random nonces
Key Storage	OS keychain (Keychain / Credential Manager / Secret Service)
Memory	Keys zeroized on drop
Format	ENVCIPHER:v1:<nonce>:<ciphertext>

Designed for: Protecting secrets from accidental commits, local development encryption at rest, small team key sharing.

Not designed for: Production secret management, zero-trust environments, HSM requirements.

---

FAQ

Can I manually edit the encrypted file?

No. Use envcipher edit or the unlock-edit-lock workflow. Manual edits corrupt the format.

Can I commit the encrypted .env file?

Yes, but we recommend using .gitignore and sharing via export-key/import-key instead. Committing encrypted files is safe only if your team securely shares the key.

What if I lose my key?

Keys are stored in your OS keychain. If you lose access (e.g., fresh OS install), get a teammate to run export-key.

How do I rotate keys?

Currently manual: decrypt with old key, run init in a fresh directory to generate new key, re-encrypt.

Does it work in CI/CD?

Not recommended. Envcipher is designed for local development. CI runners have ephemeral keychains, and storing the key as a CI secret defeats the purpose. Use native secret management instead (GitHub Secrets, AWS Secrets Manager, etc.).

Can I use this on multiple projects?

Yes. Each project directory gets its own key (hashed by directory path). Moving a project folder requires re-importing the key.

---

License

MIT

---

Contributing | Code of Conduct | Security