Logo

CLI Guide

Variables & Secrets

EnvVault stores configuration in two distinct buckets: project variables (scoped to a project + environment) and organization secrets (shared across every project in the org). They are managed by different commands, but envv run merges them transparently so your application sees a single environment.

When to use which

Project Variables (envv env)

Per-project + per-environment. Use for app-specific config: feature flags, API endpoints owned by this app, local-only credentials.

Storage scope: a key set on my-app/development is invisible to my-other-app.

Organization Secrets (envv secrets)

Org-wide. Use for shared credentials that every project consumes: a single Stripe key, a shared SMTP password, a third-party SaaS token.

Storage: encrypted with AES-256-GCM at the Cloudflare edge. Auto-versioned on every update.

Project Variables Reference

# Set / update
envv env set DATABASE_URL postgres://localhost/dev
envv env set PORT 3000 -e staging

# Read
envv env get DATABASE_URL
envv env get DATABASE_URL -e staging

# List (table format)
envv env list
envv env list -e production

# Remove
envv env delete OLD_FLAG

Organization Secrets Reference

# Set / update (auto-increments version)
envv secrets set STRIPE_SECRET_KEY=sk_test_xxx
envv secrets set DATABASE_URL=postgres://prod/db -e production

# Read decrypted value
envv secrets get DATABASE_URL -e production

# List (key, version, updated-at)
envv secrets list
envv secrets list -e production

How envv run Merges Them

When you launch a process with envv run, three sources are layered together. Higher layers win on key conflicts:

Highest priority — system environment
Project variables (envv env)
Organization secrets (envv secrets)

The system environment always wins. If you export DATABASE_URL=... before calling envv run, your shell value is preserved. This makes envv run safe to use inside CI runners that already inject their own variables.

Project variables override organization secrets. Use this to specialize a generic org-wide value for a single project.

To inspect the merged environment without launching a process:

envv run env

Encrypted Local Cache

For repeated runs (build loops, test watchers) you can cache the merged environment locally:

envv run --env-cache -- npm run dev

Cached payloads are stored at ~/.envv/cache/ encrypted with AES-256-GCM. The cache TTL is 24 hours; files older than 7 days are pruned automatically. Disable the cache (default) to always hit the API.

Best Practices

Org secrets for shared credentials. If two projects need the same Stripe key, store it once at the org level.

Project variables for app-specific config. Database URLs, ports, feature flags — anything tied to one app belongs in envv env.

Don't reuse production keys in lower environments. Set per-env values explicitly.

Audit reads. The dashboard logs every SECRET_READ and SECRET_SET; check /dashboard/audit for unexpected activity.