@x12i/env-inject

Publish environment variables from files, strings, stdin, or objects into cloud app environments.

Current provider support:

• Cloudflare Workers

Why This Package

@x12i/env-inject helps you keep cloud runtime environment variables in sync from CI, scripts, or local workflows without manually editing dashboard settings.

It supports:

• Input from .env/.dev.vars/JSON/JSONC files, inline strings, stdin, and objects
• Case-insensitive key matching with uppercase normalization for new keys
• merge and overwrite update modes
• Secret policies (none, auto, all, and selected keys)
• CLI and TypeScript programmatic API

Install

npm install @x12i/env-inject

Use with npx without installing globally:

npx @x12i/env-inject publish --help

Authentication

Cloudflare authentication requires:

• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN

You can provide them either as flags or env vars:

export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."

No Wrangler install is required. @x12i/env-inject talks directly to Cloudflare APIs.

CLI Quick Start

Main command:

env-inject publish [options]

Aliases:

• env-inject push
• env-inject apply

Example (merge mode):

env-inject publish \
  --file .env.production \
  --provider cloudflare \
  --worker my-worker \
  --env production \
  --mode merge

This works in local shells and CI/CD without adding wrangler to your project.

Example (overwrite mode + dry run):

env-inject publish \
  --file .env.production \
  --provider cloudflare \
  --worker my-worker \
  --mode overwrite \
  --dry-run

Doctor (preflight checks)

Use doctor to validate credentials and confirm the target Worker is reachable (useful for CI and debugging auth issues):

env-inject doctor --provider cloudflare --worker my-worker --env production

Machine-readable output:

env-inject doctor --provider cloudflare --worker my-worker --json

Input Sources

Exactly one input source is required:

• --file <path>: file input (.env, .dev.vars, .json, .jsonc)
• --value <string>: inline dotenv or JSON string
• --stdin: read from stdin

Examples:

env-inject publish --value 'API_HOST=https://api.example.com' --provider cloudflare --worker api

env-inject publish --value '{"api_host":"https://api.example.com","feature_flag":true}' --provider cloudflare --worker api

cat .env.production | env-inject publish --stdin --provider cloudflare --worker api

Force format when needed:

env-inject publish --file env.txt --format dotenv --provider cloudflare --worker api

Behavior

Key normalization and matching

• Incoming keys are normalized to uppercase (api_key -> API_KEY).
• Matching against existing worker vars is case-insensitive.
• In merge mode, existing key casing is preserved when a key already exists.
• Duplicate keys after normalization are rejected (for example api_key + API_KEY).

Modes

• merge (default): add/update input keys and keep unrelated existing env vars
• overwrite: replace managed env-like vars with input set (non-env bindings are preserved)

Managed binding safety

Only env-like binding types are managed:

• plain_text
• json
• secret_text

Other Cloudflare binding types remain untouched.

Prefix scoping

Use --prefix to only manage keys with a specific prefix:

env-inject publish --file .env --provider cloudflare --worker api --mode overwrite --prefix APP_

Secrets

Secret policy options:

• --secrets none (default)
• --secrets auto (sensitive-looking keys become secrets)
• --secrets all (all keys become secrets)
• --secret <KEY> (repeatable explicit list)

Examples:

env-inject publish --file .env --provider cloudflare --worker api --secret API_KEY --secret DATABASE_URL

env-inject publish --file .env --provider cloudflare --worker api --secrets auto

Sensitive key warnings are enabled by default and can be disabled with:

--no-secret-warnings

@x12i/env-inject never includes secret values in the returned change list.

CLI Options

Usage:
  env-inject publish [options]

Input:
  --file <path>
  --value <string>
  --stdin
  --format <format>          auto | dotenv | json | jsonc (default: auto)

Provider:
  --provider <provider>      currently: cloudflare

Cloudflare:
  --worker <name>
  --env <name>
  --account-id <id>          default: CLOUDFLARE_ACCOUNT_ID
  --api-token <token>        default: CLOUDFLARE_API_TOKEN

Mode:
  --mode <mode>              merge | overwrite (default: merge)

Secrets:
  --secret <key>             repeatable
  --secrets <mode>           none | auto | all (default: none)
  --no-secret-warnings

Safety:
  --dry-run
  --yes
  --prefix <prefix>
  --fail-on-empty
  --allow-empty

Output:
  --json

Programmatic API

import { publishEnv } from "@x12i/env-inject";

const result = await publishEnv({
  provider: "cloudflare",
  mode: "merge",
  source: {
    type: "object",
    value: {
      api_host: "https://api.example.com",
      feature_flag: true,
      service_config: { timeout: 3000 }
    }
  },
  target: {
    provider: "cloudflare",
    type: "worker",
    name: "my-worker",
    environment: "production"
  },
  secrets: { mode: "auto" },
  safety: {
    dryRun: false,
    prefix: "APP_"
  },
  cloudflare: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "",
    apiToken: process.env.CLOUDFLARE_API_TOKEN ?? ""
  }
});

console.log(result.summary);

Main export:

• publishEnv(options): Promise<PublishEnvResult>

CI/CD Example

env-inject publish \
  --file .env.production \
  --provider cloudflare \
  --worker my-worker \
  --env production \
  --mode overwrite \
  --yes \
  --json

Local Development

npm install
npm run build
npm run test
npm run lint
npm run typecheck

Publishing to npm (public)

This package is configured for public publishing via:

• publishConfig.access = "public"
• scoped package name @x12i/env-inject

Publish:

npm publish --access public

Repository

• GitHub: x12i/env-inject
• SSH remote: [email protected]:x12i/env-inject.git

Wrangler Dependency Policy

• @x12i/env-inject does not require wrangler to be installed.
• The package publishes Worker vars/secrets using Cloudflare API calls directly.
• This avoids hidden external prerequisites and keeps CI setup minimal.
• If users already use Wrangler in their workflow, that is optional and separate from this package.