Batch plugin

Execute a command across multiple working directories, each inheriting the current dotenv context. Output is streamed sequentially for legibility.

Import paths

// Recommended: plugins barrel (shares type identity with cliHost)
import { batchPlugin } from '@karmaniverous/get-dotenv/plugins';
Copy

Per‑plugin subpaths remain available when needed:

import { batchPlugin } from '@karmaniverous/get-dotenv/plugins/batch';
Copy

Command

getdotenv batch [options] [command...]
Copy

Options:

• -p, --pkg-cwd Use nearest package directory as current working directory.
• -r, --root-path <string> Root path from current working directory (default: ./).
• -g, --globs <string> Space‑delimited globs under the root path (default: *).
• -c, --command <string> Command to execute (dotenv‑expanded).
• -l, --list List working directories without executing the command.
• -e, --ignore-errors Continue on error.

Notes:

• The default subcommand is cmd, so positional tokens after batch are treated as the command to run. List mode merges extra positional tokens into globs.
• Commands run with explicit env injection: { ...process.env, ...ctx.dotenv }.
• Shell resolution honors script‑level overrides and the global shell setting.
• Use --capture or GETDOTENV_STDIO=pipe to buffer outputs deterministically (e.g., CI).

Examples

List repositories matching two globs:

getdotenv batch -r ./services -g "web api" -l
Copy

Run a Node snippet in each web repo under ./services:

getdotenv --shell-off batch -r ./services -g web cmd node -e "console.log(process.cwd())"
Copy

Run a named script (resolving via scripts and honoring per‑script shell):

getdotenv batch -g "*" -c build
Copy

Plugin defaults via config

You can set default scripts, shell, rootPath, globs, and pkgCwd under plugins.batch in your config:

{
  "plugins": {
    "batch": {
      "scripts": {
        "build": { "cmd": "npm run build", "shell": "/bin/bash" }
      },
      "shell": false,
      "rootPath": "./packages",
      "globs": "*",
      "pkgCwd": false
    }
  }
}
Copy

Behavior and diagnostics

• Sequential execution reduces noise and preserves legibility. A future --concurrency option is planned (see roadmap).
• The child env is composed from the current context and parent env; use --trace [keys...] to inspect where values come from (dotenv vs parent).
• On errors, the default behavior is to stop; use --ignore-errors to continue.