@earthlink/env-sync

dotvault — sync .env / .npmrc / .gitconfig and any config file across machines and CI/CD. No AWS account required.

Install

npm i -g @earthlink/env-sync
# or as a project devDependency
npm i -D @earthlink/env-sync

Requires Node >= 20.

Quick start

# 1. Create project-config.json (first time, if not already in repo)
env-sync init

# 2. Log in — stores tokens in OS keychain (Keychain / libsecret / Credential Manager)
env-sync login -e [email protected]

# 3. Pull all synced files to local disk
env-sync pull

# 4. (Optional) Inject secrets into a dev server without writing any file
env-sync run -- npm run dev

Common workflows

| Workflow | Commands | | -------------------------------------- | ------------------------------------------------------------- | | First-time setup | env-sync init → env-sync login → env-sync pull | | Join existing project (config in repo) | env-sync login → env-sync pull | | Local dev (no .env on disk) | env-sync run -- npm run dev | | CI/CD (service token) | set ENV_SYNC_TOKEN=est_… → env-sync pull --env production | | Audit history | env-sync versions DATABASE_URL | | Roll back a secret | env-sync rollback DATABASE_URL --to 4 | | Add a file to sync | env-sync push .npmrc | | Detect committed secrets | env-sync scan . |

All commands

env-sync init                     # create project-config.json
env-sync login                    # email + password auth (Cognito)
env-sync pull                     # write .env / .npmrc etc. to local disk
env-sync run -- <cmd>             # inject secrets into child process (no file written)
env-sync set KEY=value            # set one or more secrets
env-sync delete KEY               # delete a secret
env-sync import .env.production   # bulk-import from a .env file
env-sync versions KEY             # show version history of a key
env-sync rollback KEY --to N      # restore a key to version N
env-sync list                     # list (env, file) inventory for this project
env-sync push .npmrc              # add any file to the sync set
env-sync files                    # list synced files
env-sync scan .                   # detect committed secrets (offline)
env-sync project create --name X  # create a project (headless — ADR-0018)
env-sync token list --org ID      # list service tokens
env-sync token create --org ID …  # mint a service token (shown once)
env-sync token revoke --org ID …  # revoke a service token
env-sync logout                   # remove tokens from keychain
env-sync whoami                   # report active identity (interactive user OR service token)

Run env-sync <command> --help for per-command flags and examples.

Init options

env-sync init [options]

| Option | Default | Description | | ------------------- | ---------------------------- | ---------------------------------------- | | -n, --name <name> | basename(cwd) | Project name | | --api <url> | https://api.dotvault.io/v1 | API base URL | | -f, --force | — | Overwrite existing project-config.json |

Success output:

Created project-config.json (project=my-app). Next: env-sync login && env-sync pull

Pull options

env-sync pull --project my-app --env staging --file .env.local

| Option | Description | | ---------------------- | ------------------------------------------------ | | -p, --project <name> | Override project name from project-config.json | | -E, --env <env> | development | staging | production | | -f, --file <file> | Pull only this file |

Success output (one line per file):

Wrote 12 keys to .env.local (project=my-app, env=development, file=env.local). Markers preserved.

Project config

The CLI reads project-config.json in the working directory root (generated by env-sync init, schema 2.7.0):

{
  "name": "my-app",
  "setup": {
    "bootstrap": {
      "proxy": {
        "apiUrl": "https://api.dotvault.io/v1"
      }
    },
    "envSync": {
      "enabled": true,
      "files": [".env"],
      "defaultEnv": "development"
    }
  }
}

Commit this file to your repository — it contains no secrets. The apiUrl field is the only value that must match the hosted platform.

Authentication

Token resolution order for each CLI invocation (applies to pull, run, set, delete, import, versions, rollback, list, push, files, whoami):

1. ENV_SYNC_TOKEN environment variable — est_… service tokens (CI/CD/Lambda)
2. OS keychain — set by env-sync login (interactive user)

env-sync whoami will tell you which mode is active without making a network call:

$ ENV_SYNC_TOKEN=est_ci_secret_abcdefghij env-sync whoami
Service token (ENV_SYNC_TOKEN=est_ci_secre…) — CI / Lambda mode

$ env-sync whoami
[email protected] (token expires in 2847s)

Service tokens (env-sync token …)

Org admins can manage service tokens entirely from the CLI:

# List
env-sync token list --org org_abc

# Mint (the secret is shown ONCE — save it immediately)
env-sync token create --org org_abc --name ci-prod --role viewer
# Optional: --ttl <seconds>, --project <id>

# Revoke
env-sync token revoke --org org_abc --token-id est_meta_a1b2c3d4

Admin UI alternative: app.dotvault.io → your org → Service Tokens.

Headless project creation (env-sync project create)

Create a project without the admin web console — the piece that lets Claude Code / CI onboard a repo unattended (ADR-0018). Mint a provisioner token once, then create projects with no interactive login:

# one-time (org admin): mint a provisioner token — creates projects, cannot
# read or write any secret, cannot mint tokens
env-sync token create --org org_abc --name claude-provision --role provisioner

# thereafter (headless): org is taken from the token, so --org is optional
ENV_SYNC_ADMIN_TOKEN=est_… env-sync project create --name myapp

Credential precedence for project create: ENV_SYNC_ADMIN_TOKEN → ENV_SYNC_TOKEN → keychain login. See the Claude Code onboarding runbook.

Links

• Admin console: https://app.dotvault.io
• Help & FAQ: https://app.dotvault.io/admin/help
• Full documentation: https://github.com/EarthLinkNetwork/env-sync#readme
• Source: https://github.com/EarthLinkNetwork/env-sync

Access

The Lambda proxy backend is operated by EarthLink Network. Without a Cognito account in the operator's user pool you cannot fetch secrets — this package is intentionally distributable on npm but operationally private to its tenant.

License

MIT