badgr-config-doctor

Validate your environment variables, JSON/YAML configs, file paths, and runtime versions before running — so you catch misconfig before it breaks production.

npx badgr-config-doctor --required-env API_KEY,DATABASE_URL

Free. No signup required. Runs entirely on your machine.

The problem it solves

Deployments fail because a .env variable is missing, a JSON config is malformed, or node is the wrong version. You only find out after the container starts. badgr-config-doctor runs these checks in under a second — before you deploy.

Quick start

# Check that required env vars are set
npx badgr-config-doctor --required-env API_KEY,DATABASE_URL

# Validate a JSON config string
npx badgr-config-doctor --json-text '{"port": 3000, "debug": true}'

# Validate a YAML config string
npx badgr-config-doctor --yaml-text "$(cat config.yaml)"

# Check runtime version
npx badgr-config-doctor --runtime node@20

# Combine checks and output JSON
npx badgr-config-doctor \
  --required-env API_KEY,DATABASE_URL \
  --runtime node@20 \
  --json

CLI flags

| Flag | Description | |------|-------------| | --required-env <keys> | Comma-separated env var names that must be set and non-empty | | --json-text <str> | JSON config string to parse and validate | | --yaml-text <str> | YAML config string to parse and validate | | --runtime <str> | Runtime version requirement, e.g. node@20, [email protected] | | --json | Output machine-readable JSON |

Exit codes: 0 = all checks passed or warnings only, 1 = one or more failures

What it checks

| Check | What it validates | |---|---| | Required env vars | Each key exists in process.env and is non-empty | | JSON config | String parses as valid JSON without errors | | YAML config | String has valid key: value structure | | Runtime version | Installed Node/Python version meets the requirement | | Package versions | react and react-dom major versions match (prevents mismatch crashes) |

Example output

badgr-config-doctor

  ✓  API_KEY           set
  ✗  DATABASE_URL      missing — add to .env or CI secrets
  ✓  JSON config       valid
  ✗  Runtime           node@18 found, node@20 required

  2 failures. Fix before deploying.

badgr-config-doctor

  ✓  API_KEY           set
  ✓  DATABASE_URL      set
  ✓  JSON config       valid
  ✓  Runtime           [email protected] found ✓

  All checks passed.

TypeScript API

import { runConfigDoctor } from "badgr-config-doctor";

const result = runConfigDoctor({
  env: process.env,
  requiredEnv: ["API_KEY", "DATABASE_URL"],
  jsonText: '{"port": 3000}',
  runtime: "node@20",
});

for (const check of result.checks) {
  console.log(check.status, check.label, check.detail);
}

// Fail CI if any check fails
const failed = result.checks.filter(c => c.status === "fail");
if (failed.length > 0) process.exit(1);

Types:

interface ConfigDoctorOptions {
  env?: Record<string, string | undefined>;
  requiredEnv?: string[];
  jsonText?: string;
  yamlText?: string;
  paths?: Record<string, boolean>;         // { "/path/to/file": true } = must exist
  packageVersions?: Record<string, string>;
  runtime?: string;                        // e.g. "node@20", "[email protected]"
}

interface ConfigDoctorResult {
  checks: DiagnosticCheck[];
  report: JsonReport;
}

Use before deploying to AI Badgr

Run a config preflight before launching a GPU job — so the job doesn't fail 5 minutes in because of a missing env var:

npx badgr-config-doctor --required-env HF_TOKEN,WANDB_API_KEY && badgr run python train.py

Requirements

• Node.js 18+