envilder 0.9.2 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +183 -282
  2. package/ROADMAP.md +2 -2
  3. package/docs/CHANGELOG.md +96 -0
  4. package/package.json +10 -3
package/README.md CHANGED
@@ -5,144 +5,114 @@
5
5
  </p>
6
6
 
7
7
  <p align="center">
8
- <b>Automate .env and secret management with Envilder</b><br>
9
- <span>Streamline your environment setup with AWS SSM Parameter Store or Azure Key Vault</span>
8
+ <b>One model. Your secrets. Every runtime.</b><br>
9
+ <span>Define secret mappings once. Resolve them consistently from AWS SSM or Azure Key Vault.</span>
10
10
  </p>
11
11
 
12
- ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/macalbert/envilder?utm_source=oss&utm_medium=github&utm_campaign=macalbert%2Fenvilder&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
13
-
14
12
  [![npm version](https://img.shields.io/npm/v/envilder.svg)](https://www.npmjs.com/package/envilder)
15
13
  [![npm downloads](https://img.shields.io/npm/dm/envilder.svg)](https://npmcharts.com/compare/envilder)
16
14
  [![CI Tests](https://github.com/macalbert/envilder/actions/workflows/tests.yml/badge.svg)](https://github.com/macalbert/envilder/actions/workflows/tests.yml)
17
- [![Coverage Report](https://img.shields.io/badge/coverage-report-green.svg)](https://macalbert.github.io/envilder/)
18
- [![Known Vulnerabilities](https://snyk.io/test/github/macalbert/envilder/badge.svg)](https://snyk.io/test/github/macalbert/envilder)
15
+ [![Overall Coverage](https://macalbert.github.io/envilder/badge_combined.svg)](https://macalbert.github.io/envilder/)
19
16
  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
20
17
 
21
- ## Why centralize environment variables?
18
+ ## Why Envilder?
19
+
20
+ Your new developer joins the team. They need environment variables to run the app locally.
21
+ What happens next? Someone sends API keys over Slack. Someone else digs up a wiki page
22
+ with outdated credentials. Forty-five minutes later, their `.env` file is "probably correct".
23
+
24
+ **Envilder fixes this in one command.**
25
+
26
+ You create a JSON mapping between variable names and cloud secret paths. Envilder resolves
27
+ them from AWS SSM or Azure Key Vault. The same mapping file works in local dev (CLI),
28
+ CI/CD (GitHub Action), and application startup (runtime SDKs).
29
+
30
+ ```bash
31
+ envilder --map=param-map.json --envfile=.env
32
+ ```
22
33
 
23
- Envilder is a CLI tool for .env automation, cloud secrets management, and secure environment variable sync.
24
- Generating and maintaining consistent .env files is a real pain point for any development team. From outdated
25
- secrets to insecure practices, the risks are tangible. Envilder eliminates these pitfalls by centralizing and
26
- automating secret management across real-world environments (dev, test, production) in a simple, secure, and
27
- efficient way. Use Envilder to automate .env files, sync secrets with AWS SSM Parameter Store or Azure Key Vault,
28
- and streamline onboarding and CI/CD workflows.
34
+ No SaaS middleman. No vendor lock-in. Secrets stay in your cloud.
29
35
 
30
36
  ---
31
37
 
32
- ## ❗ What Envilder solves
38
+ ## The problem
33
39
 
34
- - Desync between environments (dev, prod)
35
- - Secrets not properly propagated across team members
36
- - CI/CD pipeline failures due to outdated or missing .env files
37
- - Slow and manual onboarding processes
38
- - Security risks from sharing secrets via Slack, email, or other channels
39
- - Insecure .env practices and manual secret sharing
40
+ - **Onboarding takes hours, not seconds.** Every new developer needs someone to explain which
41
+ secrets go where. Keys get shared over Slack, pasted from wikis, or copied from a colleague's
42
+ machine. It's slow, error-prone, and insecure.
43
+ - **Every environment has its own workflow.** Local dev reads `.env` files. CI/CD uses vault
44
+ integrations. Production has its own method. Same app, three different secret workflows.
45
+ - **No single source of truth.** Without a versioned contract, dev/staging/production configs
46
+ drift apart. Deployments break. Nobody knows which config is correct.
40
47
 
41
- ## ✅ How Envilder makes life easier
48
+ ## How Envilder solves it
42
49
 
43
- - 🛡️ Centralizes secrets in AWS SSM Parameter Store or Azure Key Vault
44
- - ☁️ Multi-provider support — choose `aws` or `azure` with the `--provider` flag
45
- - ⚙️ Generates .env files automatically for every environment
46
- - 🔄 Applies changes idempotently and instantly
47
- - 🔐 Improves security: no need to share secrets manually; everything is managed via your cloud provider
48
- - 👥 Simplifies onboarding and internal rotations
49
- - 🚀 Enables cloud-native, infrastructure-as-code secret management
50
- - 🤖 Perfect for DevOps, CI/CD, and team sync
50
+ - 📋 **One mapping file for everything.** A single `param-map.json` defines what secrets your app
51
+ needs. Git-versioned, PR-reviewable, the same across every environment.
52
+ - ⚡ **Works everywhere your code runs.** CLI for local dev, GitHub Action for CI/CD, runtime SDKs
53
+ for application startup. Same file, same result.
54
+ - 🛡️ **Your cloud, zero infrastructure.** Secrets stay in AWS SSM or Azure Key Vault. No SaaS
55
+ proxy, no extra servers, no data to migrate.
51
56
 
52
57
  ---
53
58
 
54
- ## 📚 Table of Contents
55
-
56
- - [🗝️ Envilder ☁️](#️-envilder-️)
57
- - [Why centralize environment variables?](#why-centralize-environment-variables)
58
- - [❗ What Envilder solves](#-what-envilder-solves)
59
- - [✅ How Envilder makes life easier](#-how-envilder-makes-life-easier)
60
- - [📚 Table of Contents](#-table-of-contents)
61
- - [⚙️ Features](#️-features)
62
- - [🧱 Feature Status](#-feature-status)
63
- - [💾 Installation](#-installation)
64
- - [🤖 GitHub Action](#-github-action)
65
- - [🚀 Quick Start](#-quick-start)
66
- - [🎥 Video Demonstration](#-video-demonstration)
67
- - [🏁 Get Started (3 steps)](#-get-started-3-steps)
68
- - [AWS SSM (default)](#aws-ssm-default)
69
- - [Azure Key Vault](#azure-key-vault)
70
- - [📚 Quick Links](#-quick-links)
71
- - [🗺️ Mapping File Format](#️-mapping-file-format)
72
- - [Basic Format (AWS SSM — default)](#basic-format-aws-ssm--default)
73
- - [With `$config` (explicit provider)](#with-config-explicit-provider)
74
- - [`$config` Options](#config-options)
75
- - [Configuration Priority](#configuration-priority)
76
- - [🛠️ How it works](#️-how-it-works)
77
- - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
78
- - [🔍 Envilder vs. Alternatives](#-envilder-vs-alternatives)
79
- - [Secrets sync tools (direct alternatives)](#secrets-sync-tools-direct-alternatives)
80
- - [Runtime \& credential tools (not direct alternatives)](#runtime--credential-tools-not-direct-alternatives)
81
- - [When to use what](#when-to-use-what)
82
- - [Why choose Envilder?](#why-choose-envilder)
83
- - [Where Envilder fits best](#where-envilder-fits-best)
84
- - [🏁 Roadmap](#-roadmap)
85
- - [🤝 Contributing](#-contributing)
86
- - [💜 Sponsors](#-sponsors)
87
- - [📜 License](#-license)
59
+ ## ⚙️ Features
60
+
61
+ | Feature | Description |
62
+ |---------|-------------|
63
+ | 📋 **Declarative Mapping** | One JSON file defines all secrets. Git-versioned, PR-reviewable, diff-able |
64
+ | ☁️ **Multi-Provider** | AWS SSM + Azure Key Vault. No vendor lock-in |
65
+ | 🔌 **Runtime SDKs** | Load secrets into memory at app startup: [.NET](./src/sdks/dotnet/README.md), [Python](./src/sdks/python/README.md). No `.env` on disk |
66
+ | ⚙️ **GitHub Action** | Pull secrets in CI/CD. Same mapping, zero manual config |
67
+ | 🔄 **Bidirectional Sync** | Pull secrets to `.env` or push values back to the cloud |
68
+ | 🧱 **Zero Infrastructure** | No servers, no proxies, no SaaS. Uses cloud services you already have |
88
69
 
89
70
  ---
90
71
 
91
- ## ⚙️ Features
72
+ ## 🚀 Quick Start
92
73
 
93
- - 🔒 **Strict access control** — IAM policies (AWS) or RBAC (Azure) define access to secrets across stages
94
- (dev, staging, prod)
95
- - 📊 **Auditable** — All reads/writes are logged in AWS CloudTrail or Azure Monitor
96
- - 🧩 **Single source of truth** — No more Notion, emails or copy/paste of envs
97
- - 🔁 **Idempotent sync** — Only what's in your map gets updated. Nothing else is touched
98
- - 🧱 **Zero infrastructure** — Fully based on native cloud services. No Lambdas, no servers, no fuss
74
+ ### 🎥 See it in action
99
75
 
100
- ### 🧱 Feature Status
76
+ Watch how easy it is to automate your .env management in less than 1 minute:
101
77
 
102
- - 🤖 **GitHub Action** — [Integrate directly in CI/CD workflows](./github-action/README.md)
103
- - 📤 **Push & Pull** — Bidirectional sync between local `.env` and your cloud provider
104
- - ☁️ **Multi-provider** — AWS SSM Parameter Store and Azure Key Vault
105
- - 🎯 **AWS Profile support** — Use `--profile` flag for multi-account setups
78
+ ![Watch the video](https://github.com/user-attachments/assets/9f194143-117d-49f3-a6fb-f400040ea514)
106
79
 
107
- ---
80
+ ### 🏁 Get Started (2 steps)
108
81
 
109
- ## 💾 Installation
82
+ **1. Create a mapping file** (`param-map.json`):
110
83
 
111
- 🛠 Requirements:
84
+ ```json
85
+ {
86
+ "DB_PASSWORD": "/my-app/db/password",
87
+ "API_KEY": "/my-app/api-key"
88
+ }
89
+ ```
112
90
 
113
- - Node.js **v20+** (cloud-native compatible)
114
- - **AWS provider**: AWS CLI installed and configured; IAM user/role with `ssm:GetParameter`, `ssm:PutParameter`
115
- - **Azure provider**: Azure CLI installed; vault URL configured via
116
- `$config.vaultUrl` in your map file or `--vault-url` flag
91
+ **2. Generate your `.env` file:**
117
92
 
118
93
  ```bash
119
- pnpm add -g envilder
94
+ npx envilder --map=param-map.json --envfile=.env
120
95
  ```
121
96
 
122
- Or use your preferred package manager:
97
+ That's it. Your secrets are pulled from AWS SSM and written to `.env`.
98
+ Add `.env` to `.gitignore`. The mapping file is versioned and reviewable in PRs.
99
+
100
+ > 💡 Using Azure Key Vault? Add a `$config` section to your mapping file.
101
+ > See [Mapping File Format](#️-mapping-file-format) below.
102
+
103
+ ### 💾 Installation
123
104
 
124
105
  ```bash
125
106
  npm install -g envilder
126
107
  ```
127
108
 
128
- > 💡 **Want to try without installing?** Run `npx envilder --help` to explore the CLI instantly.
129
- >
130
- > 💡 **New to AWS SSM?** AWS Systems Manager Parameter Store provides secure storage for configuration data and secrets:
131
- >
132
- > - [AWS SSM Parameter Store Overview](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)
133
- > - [Setting up AWS CLI credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
134
- > - [IAM permissions for SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html)
109
+ > 💡 **No install needed?** `npx envilder` works out of the box.
135
110
  >
136
- > 💡 **New to Azure Key Vault?** Azure Key Vault safeguards cryptographic keys and secrets used by cloud apps:
137
- >
138
- > - [Azure Key Vault Overview](https://learn.microsoft.com/en-us/azure/key-vault/general/overview)
139
- > - [Setting up Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
140
- > - [Key Vault access policies](https://learn.microsoft.com/en-us/azure/key-vault/general/assign-access-policy)
111
+ > **Requirements:** Node.js v20+. AWS CLI or Azure CLI configured.
112
+ > See [full requirements](docs/requirements-installation.md).
141
113
 
142
114
  ### 🤖 GitHub Action
143
115
 
144
- Use Envilder directly in your CI/CD workflows with our official GitHub Action:
145
-
146
116
  **AWS SSM (default):**
147
117
 
148
118
  ```yaml
@@ -178,77 +148,11 @@ Use Envilder directly in your CI/CD workflows with our official GitHub Action:
178
148
  vault-url: ${{ secrets.AZURE_KEY_VAULT_URL }}
179
149
  ```
180
150
 
181
- 📖 **[View full GitHub Action documentation](./github-action/README.md)**
182
-
183
- ---
184
-
185
- ## 🚀 Quick Start
186
-
187
- ### 🎥 Video Demonstration
188
-
189
- Watch how easy it is to automate your .env management in less than 1 minute:
190
-
191
- ![Watch the video](https://github.com/user-attachments/assets/9f194143-117d-49f3-a6fb-f400040ea514)
192
-
193
- ### 🏁 Get Started (3 steps)
194
-
195
- After configuring your cloud provider credentials, you can begin managing your secrets.
196
-
197
- #### AWS SSM (default)
198
-
199
- 1. **Create a mapping file:**
200
-
201
- ```json
202
- {
203
- "DB_PASSWORD": "/my-app/db/password"
204
- }
205
- ```
206
-
207
- 2. **Push a secret to AWS SSM:**
151
+ 📖 **[Full GitHub Action docs](./github-action/README.md)**
208
152
 
209
- ```bash
210
- envilder --push --key=DB_PASSWORD --value=12345 --secret-path=/my-app/db/password
211
- ```
153
+ ### 📚 More resources
212
154
 
213
- 3. **Generate your .env file from AWS SSM:**
214
-
215
- ```bash
216
- envilder --map=param-map.json --envfile=.env
217
- ```
218
-
219
- #### Azure Key Vault
220
-
221
- 1. **Add `$config` to your mapping file:**
222
-
223
- ```json
224
- {
225
- "$config": {
226
- "provider": "azure",
227
- "vaultUrl": "https://my-vault.vault.azure.net"
228
- },
229
- "DB_PASSWORD": "my-app-db-password"
230
- }
231
- ```
232
-
233
- 2. **Pull secrets from Azure Key Vault:**
234
-
235
- ```bash
236
- envilder --map=param-map.json --envfile=.env
237
- ```
238
-
239
- Or use CLI flags to override:
240
-
241
- ```bash
242
- envilder --provider=azure --vault-url=https://my-vault.vault.azure.net --map=param-map.json --envfile=.env
243
- ```
244
-
245
- Your secrets are now managed and versioned from your cloud provider. Add `.env` to your `.gitignore` for security.
246
- Envilder is designed for automation, onboarding, and secure cloud-native workflows.
247
-
248
- ### 📚 Quick Links
249
-
250
- - [📖 Full Documentation](https://envilder.com) — Visit envilder.com for the complete guide
251
- - [Requirements & Installation](docs/requirements-installation.md)
155
+ - [📖 Full Documentation](https://envilder.com): the complete guide at envilder.com
252
156
  - [Push Command Guide](docs/push-command.md)
253
157
  - [Pull Command Guide](docs/pull-command.md)
254
158
 
@@ -256,10 +160,12 @@ Envilder is designed for automation, onboarding, and secure cloud-native workflo
256
160
 
257
161
  ## 🗺️ Mapping File Format
258
162
 
259
- The mapping file (`param-map.json`) is the core of Envilder. It maps environment variable names to secret paths
260
- in your cloud provider. You can optionally include a `$config` section to declare which provider and settings to use.
163
+ The mapping file (`param-map.json`) is the core of Envilder. It's the single model that defines
164
+ what secrets your app needs and where they live in your cloud provider. The same file is used by
165
+ the CLI, the GitHub Action, and the runtime SDKs. You can optionally include a `$config` section
166
+ to declare which provider and settings to use.
261
167
 
262
- ### Basic Format (AWS SSM — default)
168
+ ### Basic Format (AWS SSM, default)
263
169
 
264
170
  When no `$config` is present, Envilder defaults to AWS SSM Parameter Store:
265
171
 
@@ -305,7 +211,7 @@ and uses all other keys as secret mappings:
305
211
  ```
306
212
 
307
213
  > **Azure naming:** Key Vault secret names only allow alphanumeric characters and hyphens.
308
- > Envilder automatically normalizes names — slashes and underscores become hyphens
214
+ > Envilder automatically normalizes names: slashes and underscores become hyphens
309
215
  > (e.g., `/myapp/db/password` → `myapp-db-password`).
310
216
 
311
217
  ### `$config` Options
@@ -313,8 +219,8 @@ and uses all other keys as secret mappings:
313
219
  | Key | Type | Default | Description |
314
220
  | --- | --- | --- | --- |
315
221
  | `provider` | `"aws"` \| `"azure"` | `"aws"` | Cloud provider to use |
316
- | `vaultUrl` | `string` | — | Azure Key Vault URL (required when `provider` is `"azure"`) |
317
- | `profile` | `string` | — | AWS CLI profile for multi-account setups (AWS only) |
222
+ | `vaultUrl` | `string` | - | Azure Key Vault URL (required when `provider` is `"azure"`) |
223
+ | `profile` | `string` | - | AWS CLI profile for multi-account setups (AWS only) |
318
224
 
319
225
  ### Configuration Priority
320
226
 
@@ -336,152 +242,146 @@ envilder --provider=azure --vault-url=https://other-vault.vault.azure.net --map=
336
242
 
337
243
  ---
338
244
 
339
- ## 🛠️ How it works
340
-
341
- ```mermaid
342
- graph LR
343
- A["Mapping File (param-map.json)"] --> B[Envilder]:::core
344
- C["Environment File (.env or --key)"] --> B
345
- D["Cloud Credentials (AWS or Azure)"]:::cloud --> B
346
- E["AWS SSM / Azure Key Vault"]:::cloud --> B
347
- B --> F["Pull/Push Secrets"]
348
-
349
- classDef cloud fill:#ffcc66,color:#000000,stroke:#333,stroke-width:1.5px;
350
- classDef core fill:#1f3b57,color:#fff,stroke:#ccc,stroke-width:2px;
351
- ```
245
+ ## 🧩 Runtime SDKs
352
246
 
353
- 1. Define mappings in a JSON file: `{"DB_PASSWORD": "/myapp/db/password"}`
354
- 2. **Pull** secrets into a `.env` file: `envilder --map=param-map.json --envfile=.env`
355
- 3. **Push** local values back: `envilder --push --map=param-map.json --envfile=.env`
356
- 4. Envilder syncs secrets securely with AWS SSM or Azure Key Vault using your cloud credentials
357
- 5. Use `--provider=azure` to switch from the default AWS provider
358
- 6. Result: your secrets are always up-to-date, secure, and ready for any environment
247
+ Beyond the CLI and GitHub Action, Envilder provides **runtime SDKs** that resolve secrets
248
+ directly into your application's memory at startup. No `.env` file written to disk, no secrets
249
+ left behind. SDKs use the same map-file format as the CLI.
359
250
 
360
- ---
251
+ ### .NET SDK
361
252
 
362
- ## Frequently Asked Questions (FAQ)
253
+ Install via NuGet:
363
254
 
364
- **Q: What is Envilder?**
365
- A: Envilder is a CLI tool for automating .env and secret management using AWS SSM Parameter Store or Azure Key Vault.
366
-
367
- **Q: Which cloud providers are supported?**
368
- A: AWS SSM Parameter Store (default) and Azure Key Vault. Use `--provider=azure` to switch providers.
255
+ ```bash
256
+ dotnet add package Envilder
257
+ ```
369
258
 
370
- **Q: How does Envilder improve security?**
371
- A: Secrets are never stored in code or shared via chat/email. All secrets are managed and synced securely via your
372
- cloud provider.
259
+ Load secrets into `IConfiguration` or inject them into the process environment:
373
260
 
374
- **Q: Can I use Envilder in CI/CD pipelines?**
375
- A: Yes! Use the official [Envilder GitHub Action](./github-action/README.md) to pull secrets directly
376
- in your workflows — no extra setup needed.
261
+ ```csharp
262
+ // Option A: integrate with IConfiguration
263
+ var mapFile = new MapFileParser().Parse(
264
+ File.ReadAllText("secrets-map.json"));
265
+ var provider = SecretProviderFactory.Create(mapFile.Config);
377
266
 
378
- **Q: Does Envilder support multiple AWS profiles?**
379
- A: Yes, you can use the `--profile` flag to select different AWS credentials.
267
+ var config = new ConfigurationBuilder()
268
+ .AddEnvilder("secrets-map.json", provider)
269
+ .Build();
380
270
 
381
- **Q: How do I configure Azure Key Vault?**
382
- A: Add a `$config` section to your map file with `"provider": "azure"` and `"vaultUrl": "https://my-vault.vault.azure.net"`,
383
- or use `--provider=azure --vault-url=https://my-vault.vault.azure.net` CLI flags. Authentication uses Azure
384
- Default Credentials (Azure CLI, managed identity, etc.).
271
+ var dbPassword = config["DB_PASSWORD"];
385
272
 
386
- **Q: What environments does Envilder support?**
387
- A: Any environment supported by your cloud provider—dev, test, staging, production, etc.
273
+ // Option B: resolve + inject into environment
274
+ var client = new EnvilderClient(provider);
275
+ var secrets = await client.ResolveSecretsAsync(mapFile);
276
+ EnvilderClient.InjectIntoEnvironment(secrets);
277
+ ```
388
278
 
389
- **Q: Is Envilder open source?**
390
- A: Yes, licensed under MIT.
279
+ 📖 **[Full .NET SDK docs](./src/sdks/dotnet/README.md)**
391
280
 
392
- ---
281
+ ### Python SDK
393
282
 
394
- ## 🔍 Envilder vs. Alternatives
283
+ Install via uv (recommended) or pip:
395
284
 
396
- Envilder is not a secrets manager. It is a **deterministic projection layer** from cloud secret
397
- stores into `.env` files. It does not store secrets, does not require a backend, and integrates
398
- cleanly into CI/CD pipelines.
285
+ ```bash
286
+ uv add envilder
287
+ # or
288
+ pip install envilder
289
+ ```
399
290
 
400
- To make a fair comparison, it's important to separate tools by what they actually do:
291
+ Load secrets into your application with a single line:
401
292
 
402
- ### Secrets sync tools (direct alternatives)
293
+ ```python
294
+ from envilder import Envilder
403
295
 
404
- These tools manage secrets as data and project them into `.env` or runtime:
296
+ # Resolve + inject into os.environ
297
+ Envilder.load('secrets-map.json')
298
+ ```
405
299
 
406
- | Feature | Envilder | dotenv-vault | infisical |
407
- |---------|----------|-------------|----------|
408
- | **Source of truth** | External (SSM / Key Vault) | dotenv vault (SaaS) | Infisical backend |
409
- | **Sync direction** | Bidirectional | Pull only | Bidirectional |
410
- | **Declarative mapping** | ✅ JSON mapping | ❌ | ❌ |
411
- | **Multi-provider (AWS + Azure)** | ✅ | ❌ | ⚠️ (primarily its own backend) |
412
- | **Local `.env` generation** | ✅ | ✅ | ✅ |
413
- | **CI/CD integration** | ✅ Native GitHub Action | Manual | ✅ Native |
414
- | **Requires SaaS** | ❌ | ✅ | Optional |
415
- | **Self-hosted** | N/A (no server needed) | ❌ | ✅ |
416
- | **Complexity** | Low | Low | Medium |
417
- | **Vendor lock-in** | Low | High | Medium |
418
- | **Open source** | ✅ MIT | Partial | ✅ |
300
+ Or route by environment, where each environment points to its own map file:
419
301
 
420
- ### Runtime & credential tools (not direct alternatives)
302
+ ```python
303
+ from envilder import Envilder
421
304
 
422
- These tools serve different purposes and are better seen as **complements**, not competitors:
305
+ Envilder.load('production', {
306
+ 'production': 'prod-secrets.json',
307
+ 'development': 'dev-secrets.json',
308
+ 'test': None, # no secrets loaded
309
+ })
310
+ ```
423
311
 
424
- | Tool | Purpose | Manages app secrets? | Works with `.env`? |
425
- |------|---------|---------------------|-------------------|
426
- | **chamber** | Injects SSM params at runtime (`exec` with env) | ❌ | ❌ |
427
- | **aws-vault** | Safely assumes AWS IAM roles / STS credentials | ❌ | ❌ |
312
+ 📖 **[Full Python SDK docs](./src/sdks/python/README.md)**
428
313
 
429
- ### When to use what
314
+ ---
430
315
 
431
- - **Need a full vault with its own backend?** → [Infisical](https://infisical.com)
432
- - **Need SaaS simplicity for `.env` sync?** → [dotenv-vault](https://www.dotenv.org/vault)
433
- - **Need a projection layer from existing cloud stores?** → **Envilder**
316
+ ## 🛠️ How it works
434
317
 
435
- ### Why choose Envilder?
318
+ ```mermaid
319
+ graph LR
320
+ A["Mapping Model (param-map.json)"] --> B[Envilder]:::core
321
+ B --> C["CLI → .env file"]
322
+ B --> D["GitHub Action → CI/CD"]
323
+ B --> E["SDK → app memory"]
324
+ F["AWS SSM / Azure Key Vault"]:::cloud --> B
436
325
 
437
- If you already use AWS SSM or Azure Key Vault and want a lightweight, zero-infrastructure CLI
438
- that generates `.env` files from a declarative JSON mapping — without a SaaS dependency or extra
439
- servers — Envilder is the simplest path.
326
+ classDef cloud fill:#ffcc66,color:#000000,stroke:#333,stroke-width:1.5px;
327
+ classDef core fill:#1f3b57,color:#fff,stroke:#ccc,stroke-width:2px;
328
+ ```
440
329
 
441
- Envilder also brings unique strengths in **determinism** and **testability**:
330
+ 1. **Define**: create a `param-map.json` mapping env var names to cloud secret paths
331
+ 2. **Resolve**: Envilder fetches each secret from your cloud vault
332
+ 3. **Deliver**: secrets arrive as a `.env` file (CLI/GHA) or in-memory (SDKs)
333
+ 4. **Push**: rotate or add secrets from your local environment back to the cloud
442
334
 
443
- - **Versioned mappings** — your `param-map.json` lives in source control, making secret
444
- projections reproducible across environments
445
- - **Mockable architecture** — hexagonal design with port interfaces makes offline testing
446
- and CI validation straightforward
447
- - **Audit trail** — all reads/writes are logged by your cloud provider
448
- (AWS CloudTrail / Azure Monitor), not by a third-party SaaS
335
+ ---
449
336
 
450
- ### Where Envilder fits best
337
+ ## 🔍 Envilder vs. Alternatives
451
338
 
452
- Envilder generates `.env` files on disk. This is ideal for:
339
+ Envilder is not a secrets manager. It is a **configuration resolution layer** that reads from your
340
+ existing cloud vault and delivers secrets where they're needed (`.env` file, CI/CD, app memory).
341
+ No SaaS backend. No extra servers.
453
342
 
454
- - **Local development** — onboard new team members with a single command
455
- - **CI/CD pipelines** — inject secrets at build time without hardcoding them
456
- - **SSG/SSR builds** — frameworks like Next.js, Nuxt, or Astro that read env vars at build time
343
+ | | Envilder | dotenvx | Infisical |
344
+ |-|----------|---------|-----------|
345
+ | **Source of truth** | Your cloud (SSM / Key Vault) | Encrypted `.env` in git | Infisical backend |
346
+ | **Declarative mapping** | ✅ JSON file | ❌ | ❌ |
347
+ | **Multi-cloud** | ✅ AWS + Azure | ❌ | ✅ |
348
+ | **Runtime SDKs** | ✅ .NET, Python | ✅ Node.js | ✅ 6+ languages |
349
+ | **Requires SaaS** | ❌ | ❌ | Optional |
350
+ | **Infrastructure** | None | None | Server required |
457
351
 
458
- For **production runtime**, container orchestrators (ECS, Kubernetes) and platform services
459
- (Vercel, Fly.io) can inject secrets directly as environment variables — no `.env` file needed.
460
- In those cases, prefer native secret injection over writing secrets to disk.
352
+ > **When Envilder shines:** you already have secrets in AWS SSM or Azure Key Vault and want
353
+ > a versioned mapping file that resolves them everywhere: local dev, CI/CD, and app runtime.
354
+ > No data to migrate. No servers to deploy. No vendor to depend on.
461
355
 
462
- > **Coming soon:** An `--exec` mode is planned to inject secrets directly into a child process
463
- > without writing to disk (e.g., `envilder exec -- node server.js`). See the [Roadmap](./ROADMAP.md).
356
+ For detailed tool-by-tool comparison including
357
+ [chamber](https://github.com/segmentio/chamber) and
358
+ [aws-vault](https://github.com/99designs/aws-vault),
359
+ see [envilder.com](https://envilder.com).
464
360
 
465
361
  ---
466
362
 
467
- ## 🏁 Roadmap
363
+ ## 🏁 What's Next
468
364
 
469
- We're continuously improving Envilder based on community feedback. Upcoming features include:
365
+ Envilder already covers the full dev-to-production lifecycle with CLI, GitHub Action,
366
+ and runtime SDKs for .NET and Python. Here's what's coming:
470
367
 
471
- - ✅ **Azure Key Vault support** — now available alongside AWS SSM
472
- - � **Exec mode** — inject secrets into a child process without writing to disk
473
- - 🔍 **Check/sync mode** for drift detection
474
- - 🌐 **Documentation website** — dedicated docs site with guides and examples
475
- - 🧠 **Auto-discovery** for bulk parameter fetching
476
- - 🔌 **More backends** (HashiCorp Vault, GCP Secret Manager, etc.)
368
+ | Status | Feature |
369
+ |--------|---------|
370
+ | ✅ | Pull & Push: bidirectional sync between `.env` and cloud vault |
371
+ | ✅ | Multi-provider: AWS SSM + Azure Key Vault |
372
+ | ✅ | GitHub Action for CI/CD |
373
+ | ✅ | .NET SDK and Python SDK |
374
+ | 🚧 | TypeScript, Go, and Java SDKs |
375
+ | 🚧 | GCP Secret Manager |
376
+ | 🚧 | Exec mode (inject secrets without writing to disk) |
477
377
 
478
- 👉 **[View full roadmap with priorities](./ROADMAP.md)**
378
+ 👉 **[Full roadmap with priorities](./ROADMAP.md)**
479
379
 
480
380
  ---
481
381
 
482
382
  ## 🤝 Contributing
483
383
 
484
- All help is welcome — PRs, issues, ideas!
384
+ All help is welcome! PRs, issues, ideas.
485
385
 
486
386
  - 🔧 Use our [Pull Request Template](.github/pull_request_template.md)
487
387
  - 🧪 Add tests where possible
@@ -495,15 +395,16 @@ All help is welcome — PRs, issues, ideas!
495
395
 
496
396
  <p align="center">
497
397
  <a href="https://localstack.cloud" target="_blank" rel="noopener noreferrer">
498
- <img src="./src/website/public/localstack-logo-horizontal-Dark.svg#gh-light-mode-only"
499
- alt="LocalStack" height="40">
500
- <img src="./src/website/public/localstack-logo-horizontal-Light.svg#gh-dark-mode-only"
501
- alt="LocalStack" height="40">
398
+ <picture>
399
+ <source media="(prefers-color-scheme: dark)" srcset="./src/website/public/localstack-logo-horizontal-Light.svg">
400
+ <source media="(prefers-color-scheme: light)" srcset="./src/website/public/localstack-logo-horizontal-Dark.svg">
401
+ <img src="./src/website/public/localstack-logo-horizontal-Dark.svg" alt="LocalStack" height="40">
402
+ </picture>
502
403
  </a>
503
404
  </p>
504
405
 
505
406
  <p align="center">
506
- Proudly supported by <a href="https://localstack.cloud">LocalStack</a> — powering Envilder's integration tests.
407
+ Supported by <a href="https://localstack.cloud">LocalStack</a>.
507
408
  </p>
508
409
 
509
410
  ---
package/ROADMAP.md CHANGED
@@ -31,15 +31,15 @@ or directly inside application code at runtime.
31
31
  | **Azure Key Vault** | Multi-backend via `$config` map-file section ([#90](https://github.com/macalbert/envilder/pull/90)) |
32
32
  | **Documentation website** | [envilder.com](https://envilder.com) |
33
33
  | **Onboarding documentation** | [Setup guide](./docs/requirements-installation.md) |
34
+ | **.NET SDK** (`Envilder`) | First runtime SDK — load secrets into `IConfiguration` or `EnvilderClient`. AWS SSM + Azure Key Vault. [Documentation](./src/sdks/dotnet/README.md) |
35
+ | **Python SDK** (`envilder`) | Runtime library for Python — Django, FastAPI, data pipelines. Sync API with `EnvilderClient`, `MapFileParser`, `SecretProviderFactory`. AWS SSM + Azure Key Vault. Published to PyPI. [Documentation](./src/sdks/python/README.md) |
34
36
 
35
37
  ### 🔥 Up Next
36
38
 
37
39
  | Feature | Priority | Notes |
38
40
  |---------|----------|-------|
39
41
  | **TypeScript SDK** (`@envilder/sdk`) | 🔴 High | Native runtime library — load secrets directly into `process.env` from a map-file. No `.env` file needed. Published to npm |
40
- | **Python SDK** (`envilder`) | 🔴 High | Runtime library for Python — Django/FastAPI/data pipelines. Published to PyPI |
41
42
  | **Go SDK** (`envilder`) | 🔴 High | Runtime library for Go — cloud-native apps, Kubernetes tooling. Published as Go module |
42
- | **.NET SDK** (`Envilder`) | 🔴 High | Runtime library for .NET — enterprise apps, Azure-native shops. Published to NuGet |
43
43
  | **Java SDK** (`envilder`) | 🔴 High | Runtime library for Java/Kotlin — Spring Boot, Android backends. Published to Maven Central |
44
44
  | **Map-file JSON Schema** | 🔴 High | Formal spec for the map-file format at `spec/` — serves as the contract between all SDKs and tools |
45
45
  | **SDK conformance tests** | 🔴 High | Language-agnostic test fixtures (JSON input → expected output) that all SDKs must pass |
package/docs/CHANGELOG.md CHANGED
@@ -1,3 +1,99 @@
1
+ ## [0.9.3] - 2026-04-17
2
+
3
+ ### Added
4
+
5
+ * **Runtime SDKs now available** — Load secrets directly into your application
6
+ at startup, no `.env` file needed:
7
+
8
+ **.NET** ([NuGet](https://www.nuget.org/packages/Envilder)):
9
+
10
+ ```csharp
11
+ builder.Configuration.AddEnvilder(
12
+ "secrets-map.json", provider);
13
+ ```
14
+
15
+ **Python** ([PyPI](https://pypi.org/project/envilder)):
16
+
17
+ ```python
18
+ from envilder import Envilder
19
+ Envilder.load('secrets-map.json')
20
+ ```
21
+
22
+ **CLI** (as always):
23
+
24
+ ```bash
25
+ npx envilder --map=secrets-map.json --envfile=.env
26
+ ```
27
+
28
+ **GitHub Action:**
29
+
30
+ ```yaml
31
+ - uses: macalbert/envilder/github-action@v0
32
+ with:
33
+ map-file: secrets-map.json
34
+ env-file: .env
35
+ ```
36
+
37
+ ### Changed
38
+
39
+ * **README rewritten** — Streamlined messaging, accurate comparison
40
+ tables, simplified quick start (2 steps), and reduced noise
41
+ * **Comparison table corrected** — Infisical SDKs, dotenvx (successor
42
+ to dotenv-vault), and chamber capabilities now accurately represented
43
+ with verified references
44
+
45
+ ### Fixed
46
+
47
+ * **ci(publish-npm):** Narrowed `paths` filter from `src/**` to
48
+ `src/envilder/**` so SDK/website/IaC changes no longer trigger the
49
+ npm publish workflow
50
+ * **ci(publish-npm):** Replaced `npm view` with `curl` against the npm
51
+ registry API to avoid `.npmrc` auth failures during version detection
52
+ * **ci(publish-website):** Added `docs/CHANGELOG.md` and
53
+ `docs/changelogs/**` to path filters so changelog updates trigger
54
+ website deployment
55
+
56
+ ### Dependencies
57
+
58
+ * Bump `typescript` from 6.0.2 to 6.0.3
59
+
60
+ ---
61
+
62
+ ## [0.9.2] - 2026-04-02
63
+
64
+ ### Added
65
+
66
+ * **LocalStack sponsor section** — Added sponsor section to website homepage and README with LocalStack logos (dark, light, color variants) and a new `Sponsors.astro` component ([#136](https://github.com/macalbert/envilder/pull/136))
67
+ * **SDK platform scaffolding** — Added placeholder structure under `src/sdks/` for future .NET, Go, Java, Python, and TypeScript SDK implementations
68
+ * **Website test suite** — Added `tests/website/` with Vitest coverage for i18n utilities and Markdown helpers (`utils.test.ts`, `markdown.test.ts`)
69
+ * **`BackToTop` component** — New scroll-to-top button component for the documentation website
70
+
71
+ ### Changed
72
+
73
+ * **Project layout restructured for SDK platform readiness** ([#134](https://github.com/macalbert/envilder/pull/134)):
74
+ * Core domain layer moved from `src/envilder/` to `src/envilder/core/`
75
+ * Website moved from `src/apps/website/` to `src/website/`
76
+ * All imports, `tsconfig.json`, `package.json`, and workspace config updated accordingly
77
+ * **Website UX improvements** — `DocsContent`, `HowItWorks`, `ThemeSwitcher`, `TerminalMockup`, and `BaseLayout` components updated; global CSS expanded; i18n keys added for new content
78
+
79
+ ### Fixed
80
+
81
+ * **README:** Replace `#gh-light-mode-only` / `#gh-dark-mode-only` image fragments with a `<picture>` element using `prefers-color-scheme` media queries for reliable dark/light theme logo switching
82
+ * **ci:** Update version check in publish workflow to use published version from npm
83
+
84
+ ### Dependencies
85
+
86
+ * Bump `@aws-sdk/client-ssm` from 3.1019.0 to 3.1021.0 ([#140](https://github.com/macalbert/envilder/pull/140))
87
+ * Bump `@aws-sdk/credential-providers` from 3.1019.0 to 3.1021.0 ([#142](https://github.com/macalbert/envilder/pull/142))
88
+ * Bump `secretlint` from 11.4.0 to 11.4.1 ([#141](https://github.com/macalbert/envilder/pull/141))
89
+ * Bump `@secretlint/secretlint-rule-preset-recommend` from 11.4.0 to 11.4.1 ([#144](https://github.com/macalbert/envilder/pull/144))
90
+ * Bump `astro` from 6.1.1 to 6.1.2 ([#143](https://github.com/macalbert/envilder/pull/143))
91
+ * Bump `actions/configure-pages` from 5 to 6 ([#139](https://github.com/macalbert/envilder/pull/139))
92
+ * Bump `actions/deploy-pages` from 4 to 5 ([#138](https://github.com/macalbert/envilder/pull/138))
93
+ * Bump `pnpm/action-setup` from 4 to 5 ([#137](https://github.com/macalbert/envilder/pull/137))
94
+
95
+ ---
96
+
1
97
  ## [0.9.1] - 2026-03-30
2
98
 
3
99
  ### Added
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "envilder",
3
- "version": "0.9.2",
3
+ "version": "0.9.3",
4
4
  "description": "A CLI and GitHub Action that securely centralizes your environment variables from AWS SSM or Azure Key Vault as a single source of truth",
5
5
  "homepage": "https://envilder.com",
6
6
  "author": {
@@ -38,7 +38,9 @@
38
38
  "release-major": "pnpm version major",
39
39
  "release-prerelease": "pnpm version prerelease",
40
40
  "dev:run": "node --env-file=dev.env --import tsx src/envilder/apps/cli/Index.ts",
41
- "docker:up": "docker compose -f docker-compose.yml up -d",
41
+ "env:generate": "pnpx envilder --map=secrets-map.json --envfile=.env",
42
+ "env:ensure": "node -e \"require('fs').existsSync('.env')||process.exit(1)\" || pnpm env:generate",
43
+ "docker:up": "pnpm env:ensure && docker compose -f docker-compose.yml up -d",
42
44
  "docker:down": "docker compose -f docker-compose.yml down"
43
45
  },
44
46
  "keywords": [
@@ -123,6 +125,11 @@
123
125
  "protobufjs",
124
126
  "sharp",
125
127
  "ssh2"
126
- ]
128
+ ],
129
+ "overrides": {
130
+ "defu": ">=6.1.5",
131
+ "lodash": ">=4.18.0",
132
+ "vite": ">=7.3.2"
133
+ }
127
134
  }
128
135
  }