Getting Started

This page gives you four fast on‑ramps. Each section includes a minimal snippet and links to the right deep‑dive.

Deprecations

• The package currently re-exports z as a convenience, but this is deprecated. Import { z } from zod directly; the re-export will be removed in v7.

1) Run a one‑off command with your env

Use the parent alias so flags apply to getdotenv, not the inner command. Prefer single quotes to avoid outer‑shell expansion.

npx @karmaniverous/get-dotenv -c 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
Copy

Tips:

• Diagnostics without altering runtime values: add --trace [keys...] and --redact. Set GETDOTENV_STDIO=pipe or pass --capture for CI‑friendly buffering.
• Default shells are normalized: /bin/bash on POSIX and powershell.exe on Windows; see Shell execution behavior.
• See the cmd plugin for more patterns and quoting guidance.

2) Load programmatically

Compose env from dotenv files and overlays in code.

import { getDotenv } from '@karmaniverous/get-dotenv';

const vars = await getDotenv({
  env: 'dev',
  paths: ['./'],
  // dynamicPath: './.env.js' or pass dynamic: defineDynamic({...})
});

console.log(vars.APP_SETTING);
Copy

Next:

• Put defaults and validation in getdotenv.config.json|yaml|js|ts using Config files and overlays.
• Use dynamic or dynamicPath for computed values; see Dynamic variables (JS/TS).
• TypeScript: helper APIs such as env overlays/expansion accept readonly record inputs (e.g., as const) to keep inference strong without casts.

3) Embed a CLI quickly (included plugins)

Prefer the named factory to get a small runner with the shipped plugins installed.

#!/usr/bin/env node
import { createCli } from '@karmaniverous/get-dotenv/cli';

await createCli({ alias: 'toolbox' })();
Copy

Notes:

• createCli installs cmd, batch, aws, and init by default. -h/--help prints help and returns. See Shell execution behavior and Shipped Plugins.
• If you need to customize which plugins are installed (omit or add your own), wire a Custom host instead.

CommonJS usage (dynamic import):

(async () => {
  // The package is ESM-only; use dynamic import from CommonJS.
  const { createCli } = await import('@karmaniverous/get-dotenv/cli');

  // Build and run your CLI with args
  const run = createCli({ alias: 'toolbox' });
  await run(['-h']);
})();
Copy

4) Scaffold config and a CLI skeleton

Use init to copy templates and a host‑based CLI skeleton into your project.

# JSON config + .local + CLI named "acme"
npx @karmaniverous/get-dotenv init . \
  --config-format json \
  --with-local \
  --cli-name acme \
  --force
Copy

or a TypeScript config with dynamic examples:

npx @karmaniverous/get-dotenv init ./apps/toolbox \
  --config-format ts \
  --cli-name toolbox
Copy

Notes:

• Collision flow: interactive overwrite/example/skip with “all” variants; CI defaults to skip unless --force. See init.
• The CLI skeleton wires the plugin‑first host; __CLI_NAME__ tokens are replaced with your chosen name.

Minimal skeleton (DX‑friendly; no explicit types or casts):

#!/usr/bin/env node
import { createCli } from '@karmaniverous/get-dotenv/cli';
import { helloPlugin } from './plugins/hello';

const run = createCli({
  alias: '__CLI_NAME__',
  compose: (p) => p.use(helloPlugin()),
});

await run();
Copy