@karmaniverous/get-dotenv 4.5.2 → 5.0.0-0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Jason Williscroft
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,215 +1,369 @@
-# get-dotenv
-
-Load environment variables with a cascade of environment-aware dotenv files. You can:
-
-✅ Asynchronously load environment variables from multiple dotenv files.
-
-✅ Segregate variables info distinct files:
-
-- Public files (e.g. `.env`, `env.dev`, `env.test`) are synced with your git repository.
-- Private files (e.g. `.env.local`, `env.dev.local`, `env.test.local`) are protected by `.gitignore`.
-- Global files (e.g. `.env`, `env.local`) apply to all environments.
-- Env files (e.g. `.env.dev`, `.env.dev.local`, `.env.test`, `.env.test.local`) apply to a specific environment.
-- [Dynamic files](#dynamic-processing) (`.env.js`) export logic that dynamically & progressively generates new variables or overrides current ones.
-
-✅ Dynamically specify which variables to load by type.
-
-✅ Explicitly add variables to the loaded set.
-
-✅ Extract the resulting variables to an object, `process.env`, a dotenv file, or a logger object, in any combination.
-
-✅ Customize your dotenv file directories & naming patterns.
-
-✅ Perform all of the above either programmatically or [from the command line](#command-line-interface), where you can also execute additional commands within the resulting context... including nested `getdotenv` commands that inherit the parent command's settings & context!
-
-✅ [Execute batched CLI commands](#batch-command) across multiple working directories, with each command inheriting the `getdotenv` context.
-
-✅ Set defaults for all options in a `getdotenv.config.json` file in your project root directory.
-
-✅ [Generate an extensible `getdotenv`-based CLI](https://github.com/karmaniverous/get-dotenv-child) for use in your own projects.
-
-`getdotenv` relies on the excellent [`dotenv`](https://www.npmjs.com/package/dotenv) parser and somewhat improves on [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) for recursive variable expansion.
-
-You can always use `getdotenv` directly on the command line, but its REAL power comes into play when you use it as the foundation of your own CLI. This lets you set defaults globally and configure pre- and post-hooks that mutate your `getdotenv` context and do useful things like grab an AWS session from your dev environment and add it to the command execution context.
-
-When you plug your own [`commander`](https://www.npmjs.com/package/commander) CLI commands into the `getdotenv` base, they will execute within all of the environmental context created above!
-
-## Breaking Changes
-
-In version 4.0.0, in addition to a full TypeScript refactor, I replaced the use of the unsafe `Function` constructor for dynamic variable processing with a MUCH safer dynamic module import.
-
-Dynamic importing is intrinsically asynchronous, and so far I haven't been able to figure out how to cram that into the synchronous `getDotenvSync` function. There really aren't THAT many users of this library, so rather than have async & sync versions that do different things, I just eliminated the sync version entirely.
-
-If you have a use case for sync dotenv processing and DON'T need dynamic variables, let me know and I'll put the restricted version back in. If you have an idea of how to make dynamic imports synchronous, I'm all ears!
-
-## Installation
-
-```bash
-npm install @karmaniverous/get-dotenv
-```
-
-## Usage
-
-```js
-import { getDotenv } from '@karmaniverous/get-dotenv';
-
-const dotenv = await getDotenv(options);
-```
-
-Options can be passed programmatically or set in a `getdotenv.config.json` file in your project root directory. The same file also sets default options for the `getdotenv` CLI or any child CLI you spawn from it.
-
-See the [child CLI example repo](https://github.com/karmaniverous/get-dotenv-child#configuration) for an extensiive discussion of the various config options and how & where to set them.
-
-## Dynamic Processing
-
-This package supports the full [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) syntax, with some internal performance improvements.
-
-Use the `dynamicPath` option to add a relative path to a Javascript module with a default export like this:
-
-```js
-export default {
-  SOME_DYNAMIC_VARIABLE: (dotenv) => someLogic(dotenv),
-  ANOTHER_DYNAMIC_VARIABLE: (dotenv) =>
-    someOtherLogic(dotenv.SOME_DYNAMIC_VARIABLE),
-  ONE_MORE_TIME: ({ DESTRUCTRED_VARIABLE, ANOTHER_DYNAMIC_VARIABLE }) =>
-    DESTRUCTRED_VARIABLE + ANOTHER_DYNAMIC_VARIABLE,
-};
-```
-
-If the value corresponding to a key is a function, it will be executed with the current state of `dotenv` as its single argument and the result applied back to the `dotenv` object. Otherwise, the value will just be applied back to `dotenv`. (Although if you're going to do that then you might as well just create a public global variable in the first place.)
-
-Since keys will be evaluated progressively, each successive key function will have access to any previous ones. These keys can also override existing variables.
-
-### Dynamic Processing with TypeScript
-
-Even though the rest of your project is in TypeScript, the dynamic processing module SHOULD be in JavasScript.
-
-Think about it: the module is loaded via a dynamic import, with the file name determined at run time. If you write this module in TS, you'll have to jump through some hoops to get your bundler to compile this file, and you'll have to be careful to set `dynamicPath` to reference the compiled file. That's a lot of work to do for some very simple logic.
-
-BUT... if you must, then your dynamic module's default export should be of the `GetDotenvDynamic` type, which is defined [here](./src/GetDotenvOptions.ts) and looks like this:
-
-```ts
-export type ProcessEnv = Record<string, string | undefined>;
-
-export type GetDotenvDynamicFunction = (
-  vars: ProcessEnv,
-  env: string | undefined,
-) => string | undefined;
-
-export type GetDotenvDynamic = Record<
-  string,
-  GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>
->;
-```
-
-The second argumnt `env` of the `GetDotenvDynamicFunction` type is the environment token (if any) specified in the controlling `getDotenv` call.
-
-## Command Line Interface
-
-You can also use `getdotenv` from the command line:
-
-```bash
-> npx getdotenv -h
-
-# Usage: getdotenv [options] [command]
-#
-# Base CLI.
-#
-# Options:
-#   -e, --env <string>                  target environment (dotenv-expanded)
-#   -v, --vars <string>                 extra variables expressed as delimited key-value pairs (dotenv-expanded): KEY1=VAL1 KEY2=VAL2
-#   -c, --command <string>              command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)
-#   -o, --output-path <string>          consolidated output file  (dotenv-expanded)
-#   -s, --shell [string]                command execution shell, no argument for default OS shell or provide shell string (default OS shell)
-#   -S, --shell-off                     command execution shell OFF
-#   -p, --load-process                  load variables to process.env ON (default)
-#   -P, --load-process-off              load variables to process.env OFF
-#   -a, --exclude-all                   exclude all dotenv variables from loading ON
-#   -A, --exclude-all-off               exclude all dotenv variables from loading OFF (default)
-#   -z, --exclude-dynamic               exclude dynamic dotenv variables from loading ON
-#   -Z, --exclude-dynamic-off           exclude dynamic dotenv variables from loading OFF (default)
-#   -n, --exclude-env                   exclude environment-specific dotenv variables from loading
-#   -N, --exclude-env-off               exclude environment-specific dotenv variables from loading OFF (default)
-#   -g, --exclude-global                exclude global dotenv variables from loading ON
-#   -G, --exclude-global-off            exclude global dotenv variables from loading OFF (default)
-#   -r, --exclude-private               exclude private dotenv variables from loading ON
-#   -R, --exclude-private-off           exclude private dotenv variables from loading OFF (default)
-#   -u, --exclude-public                exclude public dotenv variables from loading ON
-#   -U, --exclude-public-off            exclude public dotenv variables from loading OFF (default)
-#   -l, --log                           console log loaded variables ON
-#   -L, --log-off                       console log loaded variables OFF (default)
-#   -d, --debug                         debug mode ON
-#   -D, --debug-off                     debug mode OFF (default)
-#   --default-env <string>              default target environment
-#   --dotenv-token <string>             dotenv-expanded token indicating a dotenv file (default: ".env")
-#   --dynamic-path <string>             dynamic variables path
-#   --paths <string>                    dotenv-expanded delimited list of paths to dotenv directory (default: "./")
-#   --paths-delimiter <string>          paths delimiter string (default: " ")
-#   --paths-delimiter-pattern <string>  paths delimiter regex pattern
-#   --private-token <string>            dotenv-expanded token indicating private variables (default: "local")
-#   --vars-delimiter <string>           vars delimiter string (default: " ")
-#   --vars-delimiter-pattern <string>   vars delimiter regex pattern
-#   --vars-assignor <string>            vars assignment operator string (default: "=")
-#   --vars-assignor-pattern <string>    vars assignment operator regex pattern
-#   -h, --help                          display help for command
-#
-# Commands:
-#   batch [options]                     Batch shell commands across multiple working directories.
-#   cmd                                 Batch execute command according to the --shell option, conflicts with --command option (default command)
-#   help [command]                      display help for command
-```
-
-By default, commands (`-c` or `--command` or the `cmd` subcommand either in the base CLI or in the `batch` subcommand) execute in the default OS shell with the `dotenv` context applied. The `-S` or `--shell-off` options will turn this off, and Execa will [execute your command as Javascript](https://github.com/sindresorhus/execa/blob/main/docs/bash.md).
-
-Alternatively, you can use the `-s` or `--shell` option to specify a different shell [following the Execa spec](https://github.com/sindresorhus/execa/blob/main/docs/shell.md). This is useful if you're running a command that requires a specific shell, like `bash` or `zsh`.
-
-Finally, you can set the [`shell`](https://github.com/karmaniverous/get-dotenv-child?tab=readme-ov-file#options) default globally in your `getdotenv.config.json` file.
-
-See [this example repo](https://github.com/karmaniverous/get-dotenv-child) for a deep dive on using the `getDotenv` CLI and how to extend it for your own projects.
-
-### Batch Command
-
-The `getdotenv` base CLI includes one very useful subcommand: `batch`.
-
-This command lets you execute a shell command across multiple working directories. Executions occur within the loaded `dotenv` context. Might not be relevant to your specific use case, but when you need it, it's a game-changer!
-
-My most common use case for this command is a microservice project where release day finds me updating dependencies & performing a release in well over a dozen very similar repositories. The sequence of steps in each case is exactly the same, but I need to respond individually as issues arise, so scripting the whole thing out would fail more often than it would work.
-
-I use the `batch` command to perform each step across all repositories at once. Once you get used to it, it feels like a superpower!
-
-Lest you doubt what that kind of leverage can do for you, consider this:
-
-[![batch superpower in action](./doc/contributions.png)](https://github.com/karmaniverous)
-
-```bash
-> getdotenv batch -h
-
-# Usage: getdotenv batch [options] [command]
-#
-# Batch command execution across multiple working directories.
-#
-# Options:
-#   -p, --pkg-cwd             use nearest package directory as current working directory
-#   -r, --root-path <string>  path to batch root directory from current working directory (default: "./")
-#   -g, --globs <string>      space-delimited globs from root path (default: "*")
-#   -c, --command <string>    command executed according to the base --shell option, conflicts with cmd subcommand (dotenv-expanded)
-#   -l, --list                list working directories without executing command
-#   -e, --ignore-errors       ignore errors and continue with next path
-#   -h, --help                display help for command
-#
-# Commands:
-#   cmd                       execute command, conflicts with --command option (default subcommand)
-#   help [command]            display help for command
-```
-
-Note that `batch` executes its commands in sequence, rather than in parallel!
-
-To understand why, imagine running `npm install` in a dozen repos from the same command line. The visual feedback would be impossible to follow, and if something broke you'd have a really hard time figuring out why.
-
-Instead, everything runs in sequence, and you get a clear record of exactly what heppened and where. Also worth noting that many complex processes are resource hogs: you would not _want_ to run a dozen Serverless deployments at once!
-
-Meanwhile, [this issue](https://github.com/karmaniverous/get-dotenv/issues/7) documents the parallel-processing option requirement. Feel free to submit a PR!
-
----
-
-See more great templates & tools on [my GitHub Profile](https://github.com/karmaniverous)!
+# get-dotenv
+
+## Requirements
+
+- Node.js >= 20 (this repository pins 22.19.0 for CI/reproducibility)
+
+## API Reference
+Generated API documentation is hosted at:
+- https://docs.karmanivero.us/get-dotenv
+
+The site is built with TypeDoc from the source code in this repository.
+
+Load environment variables with a cascade of environment-aware dotenv files. You can:
+
+✅ Asynchronously load environment variables from multiple dotenv files.
+
+✅ Segregate variables info distinct files:
+
+- Public files (e.g. `.env`, `env.dev`, `env.test`) are synced with your git repository.
+- Private files (e.g. `.env.local`, `env.dev.local`, `env.test.local`) are protected by `.gitignore`.
+- Global files (e.g. `.env`, `env.local`) apply to all environments.
+- Env files (e.g. `.env.dev`, `.env.dev.local`, `.env.test`, `.env.test.local`) apply to a specific environment.
+- [Dynamic files](#dynamic-processing) (`.env.js`) export logic that dynamically & progressively generates new variables or overrides current ones.
+
+✅ Dynamically specify which variables to load by type.
+
+✅ Explicitly add variables to the loaded set.
+
+✅ Extract the resulting variables to an object, `process.env`, a dotenv file, or a logger object, in any combination.
+
+✅ Customize your dotenv file directories & naming patterns.
+
+✅ Perform all of the above either programmatically or [from the command line](#command-line-interface), where you can also execute additional commands within the resulting context... including nested `getdotenv` commands that inherit the parent command's settings & context!
+
+✅ [Execute batched CLI commands](#batch-command) across multiple working directories, with each command inheriting the `getdotenv` context.
+
+✅ Set defaults for all options in a `getdotenv.config.json` file in your project root directory.
+
+✅ [Generate an extensible `getdotenv`-based CLI](https://github.com/karmaniverous/get-dotenv-child) for use in your own projects.
+
+`getdotenv` relies on the excellent [`dotenv`](https://www.npmjs.com/package/dotenv) parser and somewhat improves on [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) for recursive variable expansion.
+
+You can always use `getdotenv` directly on the command line, but its REAL power comes into play when you use it as the foundation of your own CLI. This lets you set defaults globally and configure pre- and post-hooks that mutate your `getdotenv` context and do useful things like grab an AWS session from your dev environment and add it to the command execution context.
+
+When you plug your own [`commander`](https://www.npmjs.com/package/commander) CLI commands into the `getdotenv` base, they will execute within all of the environmental context created above!
+
+## Testing
+
+This project uses Vitest with the V8 coverage provider. Run:
+
+```bash
+npm run test
+```
+
+## Installation
+
+```bash
+npm install @karmaniverous/get-dotenv
+```
+
+## Scaffold
+
+You can scaffold config files and a host-based CLI skeleton using the built-in
+init command. Templates are shipped with the package and copied verbatim.
+
+Examples:
+
+```bash
+# JSON config + .local variant, and a CLI skeleton named "acme"
+npx getdotenv init . \
+  --config-format json \
+  --with-local \
+  --cli-name acme \
+  --force
+```
+
+```bash
+# TypeScript config with a dynamic example; CLI named "toolbox"
+npx getdotenv init ./apps/toolbox \
+  --config-format ts \
+  --cli-name toolbox
+```
+
+Collision flow (when a destination file exists):
+
+- Interactive prompt: [o]verwrite, [e]xample, [s]kip, or their “all” variants
+  [O]/[E]/[S].
+- Non-interactive detection:
+  - Treated as `--yes` (Skip All) unless `--force` is provided (Overwrite All).
+  - Considered non-interactive when stdin or stdout is not a TTY OR when a
+    CI-like environment variable is present (`CI`, `GITHUB_ACTIONS`,
+    `BUILDKITE`, `TEAMCITY_VERSION`, `TF_BUILD`).
+- Precedence:
+  - `--force` > `--yes` > auto-detect (non-interactive => Skip All).
+- Options overview:
+  - `--config-format <json|yaml|js|ts>`
+  - `--with-local` to generate `.local` alongside public config (JSON/YAML)
+  - `--cli-name <string>` for token substitution (`__CLI_NAME__`) in the CLI
+    skeleton
+  - `--force` to overwrite all; `--yes` to skip all
+
+Notes:
+
+- Templates are shipped with the package and copied verbatim.
+- The CLI skeleton replaces `__CLI_NAME__` tokens with your chosen name.
+
+## Usage
+
+````js
+import { getDotenv } from '@karmaniverous/get-dotenv';
+
+const dotenv = await getDotenv(options);```
+
+Options can be passed programmatically or set in a `getdotenv.config.json` file in your project root directory. The same file also sets default options for the `getdotenv` CLI or any child CLI you spawn from it.
+
+See the [child CLI example repo](https://github.com/karmaniverous/get-dotenv-child#configuration) for an extensiive discussion of the various config options and how & where to set them.
+
+## Dynamic Processing
+
+This package supports the full [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) syntax, with some internal performance improvements. Dynamic variables can be authored in JS or TS.
+
+Use the `dynamicPath` option to add a relative path to a Javascript module with a default export like this:
+
+```js
+export default {
+  SOME_DYNAMIC_VARIABLE: (dotenv) => someLogic(dotenv),
+  ANOTHER_DYNAMIC_VARIABLE: (dotenv) =>
+    someOtherLogic(dotenv.SOME_DYNAMIC_VARIABLE),
+  ONE_MORE_TIME: ({ DESTRUCTRED_VARIABLE, ANOTHER_DYNAMIC_VARIABLE }) =>
+    DESTRUCTRED_VARIABLE + ANOTHER_DYNAMIC_VARIABLE,
+};
+````
+
+If the value corresponding to a key is a function, it will be executed with the current state of `dotenv` as its single argument and the result applied back to the `dotenv` object. Otherwise, the value will just be applied back to `dotenv`. (Although if you're going to do that then you might as well just create a public global variable in the first place.)
+
+Since keys will be evaluated progressively, each successive key function will have access to any previous ones. These keys can also override existing variables.
+
+### TypeScript-first dynamic processing
+
+You can write your dynamic module in TypeScript and point `dynamicPath` at a `.ts` file. Install [`esbuild`](https://esbuild.github.io/) as a dev dependency to enable automatic compilation:
+
+```ts
+// dynamic.ts
+export default {
+  MY_DYNAMIC: ({ APP_SETTING = '' }) => `${APP_SETTING}-ts`,
+};
+```
+
+If `esbuild` is not installed and a direct import fails, get-dotenv attempts a
+simple fallback for single-file `.ts` modules without imports; otherwise it will
+throw with clear guidance to install `esbuild`.
+
+Programmatic users can skip files entirely and pass dynamic variables directly:
+
+```ts
+import { getDotenv, defineDynamic } from '@karmaniverous/get-dotenv';
+
+const dynamic = defineDynamic({
+  MY_DYNAMIC(vars, env) {
+    return `${vars.APP_SETTING}-${env ?? ''}`;
+  },
+});
+
+const vars = await getDotenv({ dynamic, paths: ['./'], env: 'dev' });
+```
+
+Notes:
+
+- Programmatic `dynamic` takes precedence over `dynamicPath` when both are provided.
+- Dynamic keys are evaluated progressively, so later keys can reference earlier results.
+
+#### Troubleshooting
+
+- “Unknown file extension '.ts'” when loading `dynamic.ts`:
+  - Install `esbuild` (`npm i -D esbuild`).
+
+- “Unable to load dynamic TypeScript file …”:
+  - Install `esbuild`. A simple transpile fallback exists only for trivial
+    single-file modules; any imports in `dynamic.ts` require `esbuild` bundling.
+
+## Command Line Interface
+
+You can also use `getdotenv` from the command line:
+
+```bash
+> npx getdotenv -h
+
+# Usage: getdotenv [options] [command]
+#
+# Base CLI.
+#
+# Options:
+#   -e, --env <string>                  target environment (dotenv-expanded)
+#   -v, --vars <string>                 extra variables expressed as delimited key-value pairs (dotenv-expanded): KEY1=VAL1 KEY2=VAL2
+#   -o, --output-path <string>          consolidated output file  (dotenv-expanded)
+#   -s, --shell [string]                command execution shell, no argument for default OS shell or provide shell string (default OS shell)
+#   -S, --shell-off                     command execution shell OFF
+#   -p, --load-process                  load variables to process.env ON (default)
+#   -P, --load-process-off              load variables to process.env OFF
+#   -a, --exclude-all                   exclude all dotenv variables from loading ON
+#   -A, --exclude-all-off               exclude all dotenv variables from loading OFF (default)
+#   -z, --exclude-dynamic               exclude dynamic dotenv variables from loading ON
+#   -Z, --exclude-dynamic-off           exclude dynamic dotenv variables from loading OFF (default)
+#   -n, --exclude-env                   exclude environment-specific dotenv variables from loading
+#   -N, --exclude-env-off               exclude environment-specific dotenv variables from loading OFF (default)
+#   -g, --exclude-global                exclude global dotenv variables from loading ON
+#   -G, --exclude-global-off            exclude global dotenv variables from loading OFF (default)
+#   -r, --exclude-private               exclude private dotenv variables from loading ON
+#   -R, --exclude-private-off           exclude private dotenv variables from loading OFF (default)
+#   -u, --exclude-public                exclude public dotenv variables from loading ON
+#   -U, --exclude-public-off            exclude public dotenv variables from loading OFF (default)
+#   -l, --log                           console log loaded variables ON
+#   -L, --log-off                       console log loaded variables OFF (default)
+#   -d, --debug                         debug mode ON
+#   -D, --debug-off                     debug mode OFF (default)
+#   --default-env <string>              default target environment
+#   --dotenv-token <string>             dotenv-expanded token indicating a dotenv file (default: ".env")
+#   --dynamic-path <string>             dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)
+#   --paths <string>                    dotenv-expanded delimited list of paths to dotenv directory (default: "./")
+#   --paths-delimiter <string>          paths delimiter string (default: " ")
+#   --paths-delimiter-pattern <string>  paths delimiter regex pattern#   --private-token <string>            dotenv-expanded token indicating private variables (default: "local")
+#   --vars-delimiter <string>           vars delimiter string (default: " ")
+#   --vars-delimiter-pattern <string>   vars delimiter regex pattern
+#   --vars-assignor <string>            vars assignment operator string (default: "=")
+#   --vars-assignor-pattern <string>    vars assignment operator regex pattern
+#   -h, --help                          display help for command
+#
+# Commands:
+#   batch [options]                     Batch shell commands across multiple working directories.
+#   cmd                                 Batch execute command according to the --shell option, conflicts with --command option (default command)
+#   help [command]                      display help for command
+```
+
+### Default shell behavior
+
+To normalize behavior across platforms, the CLI resolves a default shell when `--shell` is true or omitted:
+
+- POSIX: `/bin/bash`
+- Windows: `powershell.exe`
+
+### Batch Command
+
+The `getdotenv` base CLI includes one very useful subcommand: `batch`.
+
+This command lets you execute a shell command across multiple working directories. Executions occur within the loaded `dotenv` context. Might not be relevant to your specific use case, but when you need it, it's a game-changer!
+
+My most common use case for this command is a microservice project where release day finds me updating dependencies & performing a release in well over a dozen very similar repositories. The sequence of steps in each case is exactly the same, but I need to respond individually as issues arise, so scripting the whole thing out would fail more often than it would work.
+
+I use the `batch` command to perform each step across all repositories at once. Once you get used to it, it feels like a superpower!
+
+Lest you doubt what that kind of leverage can do for you, consider this:
+
+[![batch superpower in action](./assets/contributions.png)](https://github.com/karmaniverous)
+
+```bash
+> getdotenv batch -h
+
+# Usage: getdotenv batch [options] [command]
+#
+# Batch command execution across multiple working directories.
+#
+# Options:
+#   -p, --pkg-cwd             use nearest package directory as current working directory
+#   -r, --root-path <string>  path to batch root directory from current working directory (default: "./")
+#   -g, --globs <string>      space-delimited globs from root path (default: "*")
+#   -c, --command <string>    command executed according to the base --shell option, conflicts with cmd subcommand (dotenv-expanded)
+#   -l, --list                list working directories without executing command
+#   -e, --ignore-errors       ignore errors and continue with next path
+#   -h, --help                display help for command
+#
+# Commands:
+#   cmd                       execute command, conflicts with --command option (default subcommand)
+#   help [command]            display help for command
+```
+
+Note that `batch` executes its commands in sequence, rather than in parallel!
+
+To understand why, imagine running `npm install` in a dozen repos from the same command line. The visual feedback would be impossible to follow, and if something broke you'd have a really hard time figuring out why.
+
+Instead, everything runs in sequence, and you get a clear record of exactly what heppened and where. Also worth noting that many complex processes are resource hogs: you would not _want_ to run a dozen Serverless deployments at once!
+
+Meanwhile, [this issue](https://github.com/karmaniverous/get-dotenv/issues/7) documents the parallel-processing option requirement. Feel free to submit a PR!
+
+---
+
+### Authoring npm scripts and the `-c`/`--cmd` alias
+
+When you run commands via `npm run`, flags after `--` are forwarded to your script
+and may be applied to the inner shell command instead of `getdotenv` unless you
+structure your script carefully.
+
+- Anti-pattern:
+
+  ```json
+  { "scripts": { "script": "getdotenv echo $APP_SETTING" } }
+  ```
+
+  Then `npm run script -- -e dev` applies `-e` to `echo`, not to `getdotenv`.
+
+- Recommended:
+  ```json
+  { "scripts": { "script": "getdotenv -c 'echo $APP_SETTING'" } }
+  ```
+  Now `npm run script -- -e dev` applies `-e` to `getdotenv`, which loads and expands
+  variables before executing the inner command.
+
+Notes:
+
+- `-c`/`--cmd` is an alias of the `cmd` subcommand; do not use both in a single invocation.
+- On POSIX shells, prefer single quotes to prevent the outer shell from expanding `$VAR`
+  before Node sees it. On PowerShell, single quotes are also literal.
+- Script-level shell overrides (`scripts[name].shell`) still take precedence over the global
+  `--shell`.
+
+Important:
+
+- When using the parent alias `--cmd` with a Node eval payload, quote the entire
+  payload as a single token so Commander does not treat `-e/--eval` as
+  getdotenv’s `-e, --env` flag.
+  - POSIX example:
+    ```
+    getdotenv --cmd 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
+    ```
+  - PowerShell example (single quotes are literal in PowerShell):
+    ```
+    getdotenv --cmd 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
+    ```
+- If you do not need to pass additional parent flags after the command, you can
+  prefer the subcommand form instead:
+  ```
+  getdotenv --shell-off cmd node -e "console.log(process.env.APP_SETTING ?? '')"
+  ```
+
+Diagnostics and CI capture:
+
+- To capture child stdout/stderr deterministically (e.g., in CI), either set
+  the environment variable `GETDOTENV_STDIO=pipe` or pass `--capture`. Outputs
+  are buffered and re-emitted after completion.
+- For debugging environment composition, use:
+  ```
+  getdotenv --trace [keys...] cmd node -e "0"
+  ```
+  When provided without keys, `--trace` emits a concise origin line for every
+  key (parent | dotenv | unset) to stderr before the child process launches.
+
+---
+
+## Guides
+
+- [Cascade and precedence](./guides/cascade.md)
+- [Shell execution behavior and quoting](./guides/shell.md)
+
+The guides are also included in the [hosted API docs](https://docs.karmanivero.us/get-dotenv).
+
+---
+
+## Generated CLI
+
+This package still supports generating a standalone CLI for your projects.
+For most use cases we recommend the new plugin-first host because it resolves
+dotenv context once per invocation, supports composable plugins, and provides
+better subprocess control and diagnostics. If you prefer a thin, fixed
+command surface with defaults baked into config, the generated CLI can be a
+good fit.
+
+See the Generated CLI guide for details:
+https://docs.karmanivero.us/get-dotenv/guides/generated-cli
+
+See more great templates & tools on [my GitHub Profile](https://github.com/karmaniverous)!