Envault CLI

The Envault CLI is the fastest way to work with project secrets across development, preview, and production without leaving your terminal.

Installation

Universal Script (Recommended)

The easiest way to install Envault on macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/DinanathDash/Envault/main/install.sh | sh

Homebrew (macOS & Linux)

If you use Homebrew, you can install Envault via our official tap.

brew tap DinanathDash/envault
brew install envault

JS Package Managers

Envault is available as an NPM package, allowing you to use it with any Node.js package manager.

npm install -g @dinanathdash/envault

pnpm add -g @dinanathdash/envault

yarn global add @dinanathdash/envault

bun add -g @dinanathdash/envault

You can also run it directly without global install:

npx @dinanathdash/envault <command>

Global Flags

All commands accept these global flags:

• --config <path>: Use a specific config file instead of ~/.envault/config.toml
• -e, --env <slug>: Target environment (development, preview, production, or any valid project environment slug)
• -v, --version: Print CLI version

Quick Workflow

# 1) Authenticate once
envault login

# 2) Link current directory to a project
envault init

# 3) Inspect current context (user, role, project, environment)
envault status

# 4) Pull one environment to local file
envault pull --env preview --file .env.preview

# 5) Compare local vs remote before deploy
envault diff --env preview --file .env.preview

# 6) Deploy to target environment
envault deploy --env preview --file .env.preview

See Commands for full details.

Environment-Scoped Local Files

When a command needs a local env file (pull, diff, deploy), Envault resolves file path in this order:

1. --file
2. envault env map --env <slug> --file <path>
3. Auto-detected .env* candidate in current directory (example/sample/template files are ignored)
4. Fallback .env

Recommended setup:

envault env map --env development --file .env.development
envault env map --env preview --file .env.preview
envault env map --env production --file .env.production
envault env default --env development

Then run commands without repeating --file.

Command Index

• envault login: authenticate via device flow
• envault init: link current directory to a project
• envault status: show auth/project/environment context
• envault pull: fetch remote secrets into local file
• envault diff: show local vs remote key/value drift
• envault deploy or envault push: push local secrets to remote
• envault run -- <cmd>: run a command with injected secrets
• envault env map|unmap|default: manage local file mappings/default env
• envault version or envault --version: print version
• envault completion <shell>: generate shell completion

Authentication & Sessions

Envault CLI relies on secure Device Flow for interactive authentication. When you run envault login:

• A 30-day Refresh Token is generated and saved securely in your native OS Secure Enclave (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
• A 1-hour Access Token is stored in your configuration file (~/.envault/config.toml).

The CLI features an Auto-Refresh Interceptor. If your access token expires, the CLI silently securely requests a new one using your keyring refresh token and retries your command without failing, creating a seamless rolling session.

Automatic Updates

Envault performs a non-blocking update check after commands and shows a hint when a newer release is available.

Environment Variables

The Envault CLI uses the following environment variables for configuration:

Using Local Instance

To test against a local instance of Envault:

export ENVAULT_CLI_URL="https://envault.localhost:1355/api/cli"
envault login