@punks/dotenvs

Sync untracked dotenv files to and from S3 by git repository.

@punks/dotenvs provides the dp-dotenvs CLI for teams that keep local .env files out of git but still want a shared, repository-aware backup and restore flow. It only syncs untracked .env and .env.* files discovered by git. Tracked dotenv files are never uploaded.

Requirements

• Node.js 20 or newer
• AWS credentials with access to the target S3 bucket
• Git, because repository roots and untracked files are discovered through git

Install

Install the published CLI globally:

npm install --global @punks/dotenvs

You can also run it with pnpm:

pnpm add --global @punks/dotenvs

Configure

Log in once with the S3 bucket and optional base prefix where dotenv files should be stored:

dp-dotenvs login s3://my-bucket/optional/base-prefix --region eu-west-1

This writes a local config file at:

~/.config/dp-dotenvs/config.json

If XDG_CONFIG_HOME is set, the config is written under that directory instead.

Usage

Upload untracked dotenv files from the current git repository:

dp-dotenvs push

Scan from a specific folder instead of the current directory:

dp-dotenvs push --root ../workspace
dp-dotenvs pull --root ../workspace

Restore dotenv files:

dp-dotenvs pull

When pull runs inside a git repository, it restores files for that repository only. When it runs outside a git repository, it scans below the selected root folder for repository roots and restores matching files for each repo. The selected root defaults to the current directory. During multi-repo scans, repositories without an origin remote are skipped and included in the final recap.

Overwrite existing local dotenv files without prompting:

dp-dotenvs pull --yes

Skip existing local dotenv files:

dp-dotenvs pull --skip-existing

What Gets Synced

push uploads files matching:

• .env
• .env.*

Only untracked files are uploaded, including ignored files. Files already tracked by git are skipped.

Development

Install dependencies:

pnpm install

Build the CLI:

pnpm run build

Run tests:

pnpm test

Run the local CLI after building:

node bin/dp-dotenvs --help

Publish To npm

Before publishing, make sure the version in package.json has been updated and tests pass:

pnpm install
pnpm test
pnpm build
npm publish

After publishing, users can install the CLI globally with:

npm install --global @punks/dotenvs
dp-dotenvs --help