CLI Guide

Basic Commands

The envv binary is grouped into eight categories. Every command accepts --help to print usage and flag details. envvault is also accepted as an alias for envv.

Most commands respect three environment variables: ENVVAULT_TOKEN (auth), ENVVAULT_PROJECT (project ID override), and ENVVAULT_ENV (environment override). You can also pass a self-hosted backend with ENVVAULT_API_URL.

Authentication

envv login [--token TOKEN]

Authenticate the CLI. Stores the API key in the system keyring (with a fallback to ~/.envv/config.json).

Flag	Description
--token, -t	API key. If omitted, the CLI prompts interactively.

# Interactive
envv login

# Non-interactive (CI)
envv login --token evk_xxxxxxxxxxxxxxxxx

envv logout

Clear the local token, organization context, and the .envv.json file in the current directory.

envv logout

Projects

envv project create [-n NAME] [-d DESCRIPTION]

Create a new project in the current organization. Falls back to interactive prompts when flags are omitted.

Flag	Description
--name, -n	Project name (required, prompted if missing).
--description, -d	Optional human-readable description.

envv project create -n my-app -d "Customer-facing web app"

envv use

Interactive picker: choose a project + environment for the current directory. Writes .envv.json so subsequent envv commands inherit the selection.

envv use
# → Pick: my-app
# → Pick: development

Project Variables

Project-scoped variables live under envv env *. Every key is bound to a project + environment pair. See the Variables & Secrets guide for the variables-vs-secrets distinction.

envv env set KEY VALUE [-e ENV]

Create or update a project variable in the selected environment.

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

envv env get KEY [-e ENV]

Print the plaintext value of a single project variable.

envv env get DATABASE_URL

envv env list [-e ENV]

List all variables in the current project + environment as a table.

envv env list -e production

envv env delete KEY [-e ENV]

Remove a variable from the current project + environment.

envv env delete OLD_FLAG

Organization Secrets

Org-wide secrets are AES-256-GCM encrypted at the edge and shared across every project in the organization. Full reference at Secrets Reference.

envv secrets set KEY=VALUE [-e ENV]

Create or update an organization secret. Setting an existing key auto-increments its version.

envv secrets set STRIPE_SECRET_KEY=sk_test_abc -e development

envv secrets get KEY [-e ENV]

Print the decrypted value of an organization secret.

envv secrets get DATABASE_URL -e production

envv secrets list [-e ENV]

List all secret keys in the org with their versions and last-updated timestamps.

envv secrets list -e staging

Execution

envv run [-e ENV] [--env-cache] [--allow-partial] [-p PORT] -- COMMAND

Fetch all org secrets + project variables, merge them with the system environment, and exec the given command.

Flag	Description
-e, --env	Environment to target. Defaults to .envv.json or "development".
-p, --port	Preferred port for the child process. Auto-bumps starting at 3000 if taken.
-c, --env-cache	Cache merged variables for 24h at ~/.envv/cache (AES-256-GCM).
--allow-partial	Continue even if some variables fail to fetch.

envv run -- npm start
envv run -e production -- node server.js
envv run -e staging -p 4000 -- python manage.py runserver

Precedence (highest wins): system env → project variables → org secrets. The system env can never be overridden — set ENVVAULT_TOKEN via export and EnvVault will not clobber it.

Docker

envv docker-env [-e ENV]

Print merged variables in KEY=VALUE format suitable for piping into "docker run --env-file".

envv docker-env -e production > .env.prod
docker run --env-file=.env.prod my-image

envv docker-run [-e ENV] [--cleanup] [--restart] [--remove-volumes] -- docker COMMAND

Run any docker / docker-compose command with secrets injected. Optionally cleans up containers, volumes, or restarts services after the run.

envv docker-run -e production --restart -- docker compose up -d

Config Generators

envv generate --type=TYPE [-e ENV]

Emit a platform-specific config snippet derived from the current project + environment.

Flag	Description
--type	One of: docker, docker-compose, env, powershell, github-actions.

envv generate --type=env > .env.local
envv generate --type=github-actions >> .github/workflows/deploy.yml

Serverless

envv serverless --platform=PLATFORM [-o FILE] [-e ENV]

Emit a deploy-ready config file for a serverless platform. Output format depends on the platform.

Flag	Description
--platform	One of: aws, azure, gcp, vercel.
-o, --output	Output filename. Default depends on platform.

envv serverless --platform=aws -o lambda-env.json
envv serverless --platform=vercel -e production

Tunnel (Experimental)

envv tunnel up --port=PORT [--subdomain=NAME]

Expose a local port via a TLS-encrypted WebSocket tunnel through wss://envv.link. Useful for sharing local services or webhook testing.

Flag	Description
-p, --port	Local port to forward (required).
-H, --host	Local host. Default: localhost.
-s, --subdomain	Custom subdomain (subject to availability).
--server	Override tunnel server URL.
-v, --verbose	Verbose logging.

envv tunnel up --port=3000 --subdomain=my-demo

Help

envv --version — print the installed CLI version.

envv --help — top-level help.

envv <command> --help — per-command flags & usage.

envv docs — print the in-terminal usage banner with quick examples.