I Built a CLI to Stop Missing Env Vars from Breaking Deployments

Environment variables look boring until they break a deployment.

I kept running into the same kind of problem while building TypeScript systems:

a variable exists locally
the CI pipeline does not have it
the deployment provider does not have it
the service starts anyway
the real failure appears later, far away from the source

The bug is usually not complex.

The debugging session is.

You end up checking .env files, CI variables, GitHub Actions secrets, GitLab variables, deployment dashboards, workflow files, and trying to understand which environment is missing which key.

At some point I got tired of doing that manually, so I built a small CLI:

@hardmachinelabs/env-sync

Documentation:

https://jordachmakaya.github.io/env-sync/

Package:

https://www.npmjs.com/package/@hardmachinelabs/env-sync

Repository:

https://github.com/jordachmakaya/env-sync

The problem

Most projects start simple:

.env
.env.example
README.md

Then the project grows.

You add:

staging
production
CI
preview environments
multiple services
multiple packages
GitHub Actions
GitLab CI
deployment providers

And suddenly .env.example is no longer enough.

It documents what should exist.

It does not guarantee that the variables actually exist where the app runs.

That gap is where a lot of avoidable deployment failures happen.

The flow

Here is the basic idea:

Local project
     |
     v
Discover .env files
     |
     v
Select environment
example: production
     |
     v
Map variable names
     |
     v
Preview changes
--dry-run
     |
     v
Review output
     |
     +--> Looks wrong
     |        |
     |        v
     |   Fix .env files
     |   or naming rules
     |        |
     |        v
     |   Run dry-run again
     |
     +--> Looks correct
              |
              v
        Select provider
              |
      +-------+--------+
      |                |
      v                v
 GitHub Actions    GitLab CI/CD
 secrets           variables
 via gh CLI        via REST API
      |                |
      +-------+--------+
              |
              v
 Secrets created or updated
              |
              v
 CI/CD has the expected variables

The important part is not the sync itself.

The important part is the review step before the sync.

Secrets are not something I want a tool to change silently.

What I wanted

I did not want a big secret-management platform.

I wanted a focused tool that could answer a simple question:

“Are the environment variables my project needs actually present in the place where my pipeline runs?”

And then, when I explicitly ask for it:

“Can you sync them for me?”

So I built env-sync.

What it does

At a high level:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --sync-only

The CLI discovers .env files, maps variables, and syncs them to the selected provider.

Current targets:

GitHub Actions secrets
GitLab CI/CD variables

It also supports dry-run mode:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --sync-only --dry-run

The dry-run is the first command I expect people to run.

Not the real sync.

GitHub example

For GitHub, the CLI uses the GitHub CLI.

That means you should have gh installed and authenticated before syncing secrets.

gh auth status

Then run a dry-run:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --sync-only --dry-run

If the output looks correct, remove --dry-run:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --sync-only

The --sync-only flag is useful when your workflows already reference the expected secret names and you only want to sync repository secrets.

There is also a GitHub-specific --workflows-only mode if you want to inspect workflow YAML patching separately:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --workflows-only --dry-run

Why monorepos matter

This problem gets worse in monorepos.

You may have:

apps/web/.env
apps/api/.env
packages/worker/.env

Different services may reuse generic names:

DATABASE_URL
REDIS_URL
API_KEY

That is fine locally.

It becomes risky when everything is pushed into a shared CI/CD namespace.

So env-sync is monorepo-aware and can apply namespacing rules to reduce collisions between packages.

The goal is not to be clever.

The goal is to make the final secret names predictable.

Example output

This is the kind of output I want from a tool touching secrets:

────────────────────────────────────────────────────
🔍 env-sync  |  env: production  |  dry-run: false
────────────────────────────────────────────────────
🔍 Found 1 .env file(s)
🔍 Mapped 9 secret(s)
🔍 Provider: github
🔍 Syncing GitHub Actions secrets...
✅ Updated secret: NUXT_PUBLIC_POSTHOG_KEY
✅ Updated secret: NUXT_PUBLIC_POSTHOG_HOST
✅ Updated secret: TWENTY_BASE_URL
✅ Updated secret: TWENTY_API_KEY
✅ Updated secret: TWENTY_PORTFOLIO_REQUEST_OBJECT
✅ Updated secret: DOKPLOY_WEBHOOK_URL

Simple.

Visible.

No guessing.

Install

You can install it as a dev dependency:

pnpm add -D @hardmachinelabs/env-sync

Or run it directly:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env=production --sync-only --dry-run

For a single file instead of auto-discovery:

pnpm dlx @hardmachinelabs/env-sync --provider=github --env-file=packages/blog/.env --dry-run

Design constraints

I tried to keep the tool boring on purpose.

1. Dry-run first

I want to inspect changes before anything is written.

2. Explicit provider support

Right now it supports GitHub and GitLab because those are the providers I actually use.

I prefer a smaller tool that handles real providers properly over a generic abstraction that hides too much.

3. No hidden magic

The CLI should print what it found, what it mapped, and what it synced.

4. Small dependency surface

Deployment tooling should not bring unnecessary supply-chain risk into a project.

What this is not

It is not a replacement for Vault, Doppler, Infisical, AWS Secrets Manager, or any serious enterprise secret-management system.

It is not trying to solve every secret-management problem.

It is a focused CLI for a common failure mode:

local env, CI env, and provider secrets drifting apart.

That is the scope.

Security notes

A tool that touches secrets needs conservative usage.

The basic rules:

do not commit .env files
do not paste real secrets into issues, pull requests, screenshots, or docs
run dry-run first
review generated secret names
review workflow diffs before committing them
verify provider permissions before syncing production secrets

The tool can help reduce drift.

It cannot make unsafe secret practices safe.

Why I published it

I am preparing to publish more of the small tools that came out of building larger systems.

env-sync is one of them.

It came from a real operational pain point, not from trying to invent a library idea.

If you manage TypeScript apps, monorepos, GitHub Actions, or GitLab CI/CD, I would appreciate feedback:

Is the scope clear?
Would this fit your workflow?
What would make you trust or not trust a tool that syncs secrets?
Which provider should be supported next?

I am especially interested in feedback from people who have been burned by missing env vars in CI or production.

推荐订阅源

DEV Community