@voluspalabs/env-vault

Internal Voluspa Labs environment-vault CLI and runtime-neutral configuration helpers.

Install

Use an exact development dependency with the consumer repository's package manager:

bun add --dev --exact @voluspalabs/env-vault

The CLI runs on Bun 1.3 or newer (bunx envvault or the installed bin). envvault login stores its token through native OS credential storage on macOS, Windows, or Linux. The CLI refuses to use a plaintext credential file.

Getting started

envvault login --server https://vault.example.com   # token via masked prompt
envvault init                                       # discovers workspaces and env files
envvault provision                                  # creates the project + environments server-side
envvault pull --all                                 # writes every environment's mapped files

init reads package.json workspaces (or pnpm-workspace.yaml), recognizes stage files per directory (.env, .env.preview, .env.production, and common aliases), shows the proposed scope table, and writes .envvault.json. Manual mappings stay available via --workspace scope:path.

Commands

envvault login --server <url>
envvault logout
envvault status [--environment <name>] [--json]
envvault init [--project <slug>] [--workspace <scope:path>...] [--yes] [--force-config] [--json]
envvault provision [--json]
envvault diff --environment <name> [--all] [--local] [--yes] [--json]
envvault pull --environment <name> [--all] [--yes] [--force] [--json]
envvault push --environment <name> [--yes] [--json]
envvault example [--check] [--json]
envvault run --environment <name> [--scope <scope>] [--yes] -- <command>
envvault agent-setup [--write] [--json]

Every command supports --help, --json (a stable {ok, schema, command, data|error} envelope on stdout), and --quiet.

login reads the one-time dashboard token from a masked prompt or stdin. The CLI never accepts it as an option or positional argument.

status without --environment shows a per-environment table (entry count, pending remote changes, pulled state). diff compares your last pull against the vault's revisions; diff --local compares your local file values against the vault in memory and prints names only. pull writes ignored mapped files and refuses to clobber locally modified ones without confirmation or --force; multi-environment pulls require distinct output paths. push reads those files and creates encrypted server revisions. Existing names use the revision recorded by the last successful pull, so a remote change conflicts instead of being overwritten. A successful push records the returned revisions and current file hashes, so the next push uses the new baseline. A first push can create missing names but cannot replace a remote name that was never pulled. example regenerates tracked .env.example files from authenticated metadata names; --check verifies them locally without printing values. run retrieves values and passes them to one child process without writing a file.

Human and --json output omit values and complete tokens. Exit codes distinguish usage errors (2), authentication errors (3), conflicts and local drift (4), and I/O or server failures (5). run returns the child process exit code. --json failures carry a machine-readable error.code (see llms.txt for the full table).

Repository mapping

.envvault.json maps each scope to per-environment files:

{
  "version": 1,
  "project": "repository-slug",
  "files": [
    {
      "scope": "api",
      "overrides": ["PUBLIC_API_URL"],
      "paths": {
        "development": "apps/api/.env",
        "preview": "apps/api/.env.preview",
        "production": "apps/api/.env.production"
      }
    }
  ]
}

Each mapping needs at least one environment path; environments without a path are skipped for that scope. A root mapping is optional; root values still compose into every workspace file, and a colliding name must be listed in the workspace overrides array.

Add every mapped path, .envvault.state.json, and *.envvault-*.tmp to .gitignore before init or pull. The temporary-file wildcard is required because atomic writes stage random same-directory names. The CLI refuses unsafe output and prints the exact lines to add.

Headless and agent use

ENV_VAULT_TOKEN + ENV_VAULT_SERVER (set together) provide a credential-store override that the CLI can read but never modify; they win over the keychain for controlled local headless processes and agent sandboxes. This does not make the credential read-only: today it is a human full-vault PAT with the same vault access as its owner and must not be placed in CI. The server validates it through /v1/status, while the format remains open for future scoped workload credentials. Environment tokens are readable by any same-user process; prefer the keychain interactively and never echo them. envvault agent-setup --write installs a Claude Code skill and prints AGENTS.md / .mcp.json snippets; the companion @voluspalabs/env-vault-mcp package exposes the same operations as MCP tools without ever returning values.

Limits

Personal access tokens may live for at most 365 days. One entry value may contain at most 65,536 UTF-8 bytes. Bulk dashboard writes accept at most 50 entries, CLI pushes at most 200, and pulls at most 1,000 entries or 8 MiB of decrypted values. Each HTTP request body may contain at most 1,048,576 bytes. The server rejects oversized input and never truncates it.

Production

Production pull, push, diff --local, and run require a typed confirmation. --yes supplies that confirmation for a deliberate non-interactive invocation.