Enchanced docs about usage

README.md

@@ -27,6 +27,25 @@ pip install envcloak[dev]
 
 ## 🚀 Example Workflow
 
+> ℹ️ More examples are present in [examples](./examples) section.
+
+### Generating key:
+
+```bash
+# With password and salt
+envcloak generate-key-from-password --password "YourTopSecretPassword" \
+--salt "e3a1c8b0d4f6e2c7a5b9d6f0cr2ad1a2" --output secretkey.key
+
+# With password without salt (we will add random salt then)
+envcloak generate-key-from-password --password "YourTopSecretPassword" --output secretkey.key
+
+# From random password and salt
+envcloak generate-key --output secretkey.key
+```
+> **What it does:** generates your private key used to encrypt and decrypt files. **Appends (or creates if needed) .gitignore as well** as super-hero should! 🎉
+
+> ⚠ **If someone knows your password and salt (option 1) can recreate same key.** ⚠
+
 ### Encrypting Variables:
 
 ```bash
@@ -41,7 +60,6 @@ envcloak decrypt --input .env.enc --output .env --key-file mykey.key
 ```
 > **What it does:** Decrypts the `.env.enc` file back to `.env` using the same key. Voilà!
 
-
 or you may want to use it ...
 
 ### 🐍 In Your Python Code

examples/README.md

@@ -0,0 +1,20 @@
+# EnvCloak Examples 📘
+
+Explore practical examples for using EnvCloak in different scenarios:
+
+## 📂 CLI Examples
+Navigate to [CLI Examples](./cli/README.md) for usage instructions and examples of using EnvCloak via the command-line interface (CLI). Perfect for quick manual operations and scripts.
+
+---
+
+## 📂 In-Code Examples
+Visit [In-Code Examples](./in_code/README.md) to learn how to use EnvCloak in Python code. Includes examples for securely loading and managing encrypted environment variables programmatically.
+
+---
+
+## 📂 Workflow Examples
+Check out [Workflow Examples](./workflow/README.md) for guidance on integrating EnvCloak into CI/CD pipelines. Covers popular platforms like GitHub Actions, GitLab CI/CD, Jenkins, and Azure Pipelines.
+
+---
+
+**Need more help?** Visit the main [README](../README.md) for an overview of EnvCloak features.

examples/cli/README.md

@@ -0,0 +1,118 @@
+# EnvCloak: CLI examples
+
+EnvCloak simplifies managing sensitive environment variables by encrypting and decrypting .env files securely. It supports generating encryption keys, encrypting/decrypting files, and rotating keys efficiently. Designed for developers and CI/CD pipelines, EnvCloak is the security superhero your project needs! 🛡️
+
+## Usage
+
+### Key Generation
+
+#### 1. Generate a Key from a Password and Salt
+
+```bash
+envcloak generate-key-from-password --password "YourTopSecretPassword" \
+--salt "e3a1c8b0d4f6e2c7a5b9d6f0cr2ad1a2" --output secretkey.key
+```
+
+**Description:** Derives a key from a password and a salt. The salt ensures uniqueness, preventing duplicate keys from identical passwords. 
+**By default:**
+* If a `.gitignore` exists, it appends the key file name to it.
+* If `.gitignore` doesn't exist, it creates one and includes the key file name.
+
+> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. ⚠
+
+#### 2. Generate a Key from a Password Without a Salt
+
+```bash
+envcloak generate-key-from-password --password "YourTopSecretPassword" --output secretkey.key
+```
+
+**Description:** Derives a key from a password and a randomly generated salt. The salt is stored for future use. 
+**By default:**
+* If a `.gitignore` exists, it appends the key file name to it.
+* If `.gitignore` doesn't exist, it creates one and includes the key file name.
+
+> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. ⚠
+
+#### 3. Generate a Random Key
+
+```bash
+envcloak generate-key --output secretkey.key
+```
+
+**Description:** Creates a random encryption key. 
+**By default:**
+* If a `.gitignore` exists, it appends the key file name to it.
+* If `.gitignore` doesn't exist, it creates one and includes the key file name.
+
+> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. ⚠
+
+### Encrypting Variables
+
+```bash
+envcloak encrypt --input .env --output .env.enc --key-file mykey.key
+```
+
+**Description:** Encrypts your `.env` file into `.env.enc`. The original file remains unchanged.
+
+### Decrypting Variables
+
+```bash
+envcloak decrypt --input .env.enc --output .env --key-file mykey.key
+```
+
+**Description:** Decrypts `.env.enc` back to `.env`. Ensure the `key-file` used matches the one from the encryption step.
+
+### Rotating Keys
+
+```bash
+envcloak rotate-keys --input .env.enc --old-key-file oldkey.key \
+--new-key-file newkey.key --output .env.enc.new
+```
+
+**Description:** Re-encrypts an encrypted file with a new key, ensuring minimal disruption when rotating encryption keys.
+
+## Use Cases
+
+### 1. Secure Environment Variables in CI/CD Pipelines
+
+Problem: Sharing sensitive data like API keys or database credentials in a CI/CD pipeline.
+Solution: Use EnvCloak to encrypt .env files during deployment:
+
+1. Before commit
+```bash
+# Generate key
+envcloak generate-key --output secretkey.key
+# Encrypt sensitive data
+envcloak encrypt --input .env --output .env.enc --key-file secretkey.key
+git add .env.enc
+git commit -m "Secure .env file"
+```
+2. During build/deploy
+```bash
+# Decrypt for normal use
+envcloak decrypt --input .env.enc --output .env --key-file secretkey.key
+```
+> You must provide `secretkey.key` in CI/CD workflow in secure way.
+
+The decrypted `.env` file is ready for use in your application.
+
+### 2. Setting Up a New Project
+
+Problem: Sharing initial credentials and configurations with your team securely.
+Solution: Encrypt the `.env` file before distributing:
+
+1. Generate key
+```bash
+envcloak generate-key --output myproject.key
+```
+2. Encrypt sensitive data
+```bash
+envcloak encrypt --input .env --output .env.enc --key-file myproject.key
+```
+Distribute the `.env.enc` file and keep the `myproject.key` secure.
+
+## Best Practices
+
+* Never commit keys: Always use `.gitignore` to exclude `key` files.
+* Secure `password`s and `salt`s: Treat them as sensitive as the `key`s themselves.
+* Automate `encryption`/`decryption`: Include EnvCloak commands in CI/CD pipelines or scripts for consistency.

examples/in_code/README.md

@@ -0,0 +1,49 @@
+# EnvCloak: In code examples
+
+EnvCloak can be easily integrated into your Python application to securely load encrypted environment variables directly into your os.environ. Here's how you can do it:
+
+## Installation
+
+Ensure you have EnvCloak installed:
+```bash
+pip install envcloak
+```
+
+## Loading Encrypted Variables in Code
+
+```python
+import os
+from envcloak import load_encrypted_env
+
+# Load encrypted environment variables from a file
+load_encrypted_env('path/to/your/env.enc', key_file='path/to/your/key.key').to_os_env()
+
+# Now os.environ contains the decrypted variables
+print("DB_USERNAME:", os.getenv("DB_USERNAME"))
+print("DB_PASSWORD:", os.getenv("DB_PASSWORD"))
+
+```
+
+you may test it on our `mock` data:
+
+```python
+# test.py file in this dir
+import os
+from envcloak import load_encrypted_env
+
+load_encrypted_env('tests/mock/variables.env.enc', key_file='tests/mock/mykey.key').to_os_env()
+# Now os.environ contains the decrypted variables
+
+# Check if specific variables are in os.environ
+print("DB_USERNAME:", os.getenv("DB_USERNAME"))
+print("DB_PASSWORD:", os.getenv("DB_PASSWORD"))
+```
+
+## Use Cases
+
+* **Secure Application Configurations:** Load sensitive variables (e.g., API keys, database credentials) without exposing them in plaintext files.
+* **Seamless CI/CD Integration:** Securely handle environment variables in automated pipelines.
+
+---
+
+`EnvCloak` makes managing sensitive configurations both simple and secure! 🌟

examples/in_code/test.py

@@ -0,0 +1,9 @@
+import os
+from envcloak import load_encrypted_env
+
+load_encrypted_env('tests/mock/variables.env.enc', key_file='tests/mock/mykey.key').to_os_env()
+# Now os.environ contains the decrypted variables
+
+# Check if specific variables are in os.environ
+print("DB_USERNAME:", os.getenv("DB_USERNAME"))
+print("DB_PASSWORD:", os.getenv("DB_PASSWORD"))