@earthlink/dotvault

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

Install

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

Requires Node >= 20.

Upgrading from @earthlink/env-sync? The env-sync command keeps working as an alias — see Compatibility alias below.

Quick start

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

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

# 3. Pull all synced files to local disk
dotvault pull

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

Common workflows

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

All commands

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

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

Init options

dotvault 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: dotvault login && dotvault pull

Pull options

dotvault 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, or any custom env the project has declared (Settings → Environments, ADR-0024) | | -f, --file <file> | Pull only this file |

Success output (one line per file, then a summary; colors/progress bar on a TTY only):

✓ Wrote 12 keys to .env.local (project=my-app, env=development, file=env.local). Markers preserved.
✔ 1 file synced, 0 excluded, 12 keys total

Project config

The CLI reads project-config.json in the working directory root (generated by dotvault 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. DOTVAULT_TOKEN environment variable (or legacy ENV_SYNC_TOKEN) — est_… service tokens (CI/CD/Lambda)
2. OS keychain — set by dotvault login (interactive user)

dotvault whoami will tell you which mode is active without making a network call:

$ DOTVAULT_TOKEN=est_ci_secret_abcdefghij dotvault whoami
Service token (DOTVAULT_TOKEN=est_ci_secre…) — CI / Lambda mode

$ dotvault whoami
[email protected] (token expires in 2847s)

Service tokens (dotvault token …)

Org admins can manage service tokens entirely from the CLI:

# List
dotvault token list --org org_abc

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

# Revoke
dotvault token revoke --org org_abc --token-id est_meta_a1b2c3d4

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

Headless project creation (dotvault 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
dotvault token create --org org_abc --name claude-provision --role provisioner

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

Credential precedence for project create: DOTVAULT_ADMIN_TOKEN (or legacy ENV_SYNC_ADMIN_TOKEN) → DOTVAULT_TOKEN (or legacy ENV_SYNC_TOKEN) → keychain login. See the Claude Code onboarding runbook.

Compatibility alias (env-sync)

The package still installs an env-sync binary alongside dotvault — every command works identically under either name. Invoking any command via env-sync prints a one-line stderr notice:

env-sync is now dotvault — the env-sync command keeps working as an alias.

Legacy ENV_SYNC_* environment variables (ENV_SYNC_TOKEN, ENV_SYNC_ADMIN_TOKEN, ENV_SYNC_API_URL) are still read as a fallback when the corresponding DOTVAULT_* variable is unset — there is no forced migration deadline.

Links

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

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