@env-vault/cli

Public npm package for pulling Age-encrypted environment files from your private EnvVault Git repository (GitHub, GitLab, or Bitbucket).

Web app: https://env-locker.vercel.app — sign in, upload envs, and download provisioning files (vault_key.enc, totp.secret).

Install

npm install -g @env-vault/cli

Setup

1. Open the EnvVault web app, sign in with your Git provider, and complete provisioning (download vault_key.enc + totp.secret).
2. Configure provider + repo + token:

envvault config set --provider github --repo owner/repo-name
envvault config set --git-token <pat-or-app-password>

For Bitbucket app passwords (Basic auth):

envvault config set --provider bitbucket --repo workspace/repo-name
envvault config set --bitbucket-username YOUR_USERNAME --git-token YOUR_APP_PASSWORD

3. Save provisioning files to the vault directory for this repo:

envvault profile path
mkdir -p "$(envvault profile path)"
mv ~/Downloads/vault_key.enc ~/Downloads/totp.secret "$(envvault profile path)/"

Each env vault repo has its own Age key and TOTP secret. Use envvault profile list to see configured profiles.

Legacy: If you already use a single repo with files directly in ~/.env-vault/, that keeps working until you add a profile folder.

Token access (private repos)

Recommended: use a read-scoped PAT or app password (envvault config set --git-token …).

| Provider | Config / env | Required access | | --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GitHub | gitToken, githubToken, GITHUB_TOKEN | Fine-grained: Contents → Read-only. Classic: repo | | GitLab | gitToken, GITLAB_TOKEN | read_api or read_repository | | Bitbucket | gitToken, bitbucketUsername, BITBUCKET_TOKEN, BITBUCKET_USERNAME | App password: Repositories → Read + your Bitbucket username (Basic auth). Or username:password in gitToken. Repository access tokens work with --git-token only. |

OAuth login (optional, less secure)

OAuth is available for convenience but stores a broader token in ~/.env-vault/config.json. Prefer a read-scoped PAT when possible.

envvault login --provider github

This opens your browser to sign in through EnvVault — you do not need to create your own OAuth app or export client secrets. EnvVault brokers the OAuth flow using its server-side credentials.

For self-hosted EnvVault:

envvault config set --env-vault-url http://localhost:3000
# or export ENV_VAULT_URL=http://localhost:3000
envvault login --provider github

Use envvault logout to clear OAuth credentials and fall back to a PAT. Setting --git-token switches back to PAT mode automatically.

Pull

envvault pull myapp/production .env

Switch repos by changing provider — EnvVault remembers a repo per Git host:

envvault config set --provider github --repo owner/github-envs
envvault config set --provider gitlab --repo group/project
envvault config set --provider gitlab   # restores the saved GitLab repo
envvault profile path                   # vault dir for the active provider + repo

Commands

| Command | Description | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | envvault pull <project>/<environment> <output> | Authenticate (2FA + passphrase), fetch, decrypt | | envvault list [project] | List available env paths in the configured repo | | envvault whoami | Show active Git provider and authenticated user | | envvault login [--provider <host>] | OAuth sign-in (shows security warning; PAT recommended) | | envvault logout | Clear stored OAuth credentials | | envvault config set --provider <github\|gitlab\|bitbucket> --repo <slug> | Git host + env vault repo | | envvault config repos | List saved repos per provider from config | | envvault config set --git-token <token> | PAT / app password for private repo access | | envvault config set --bitbucket-username <user> | Bitbucket username (required for app passwords) | | envvault config set --env-vault-url <url> | EnvVault server for brokered OAuth (self-hosted) | | envvault config set <key> <value> | Legacy single-key config (provider, repo, gitToken, bitbucketUsername, githubToken) | | envvault profile list | List per-repo vault directories | | envvault profile path | Print vault dir for current provider + repo |

Multi-provider vault layout

~/.env-vault/
  config.json              # active provider, per-provider repos, token
  vault_key.enc              # legacy single-repo install (optional)
  totp.secret
  profiles/
    github__owner__repo-a/
      vault_key.enc
      totp.secret
    gitlab__group__project/
      vault_key.enc
      totp.secret

Each Git repo you use with EnvVault gets its own profile folder because each repo has a unique Age encryption key created at first upload.

Security

• TOTP and passphrase verification happen locally — no EnvVault server call on pull.
• Age identity is unlocked in memory for one operation, then discarded.
• Config and vault files use restrictive permissions (0600 / 0700).

Publishing (maintainers)

1. Add NPM_TOKEN (Automation) to GitHub repository secrets.
2. Create a GitHub Release to trigger .github/workflows/publish-cli.yml.

The EnvVault web app repository can remain private; only this CLI package is public on npm.