envault-manager - SKILL.md Agent Skill

name: envault-manager description: Use when managing environment variables across projects, working with .env files, setting up project secrets, or using the envault CLI tool for centralized env var management

Envault Manager

Overview

Envault is a centralized environment variable management CLI tool that stores variables in a SQLite database (~/.envault/envault.db) while keeping .env files in sync. It uses git repository roots to identify projects and provides a structured, AI-friendly interface for managing environment variables across multiple projects and environments.

Core principle: One database for all projects, with bidirectional sync between the database (store) and project .env files.

Installation

Before using envault, always check if it's installed:

# Check if envault is installed and get version
envault --version

# If not installed, you'll see: "command not found: envault"
# If installed, you'll see: "envault 0.1.0" (or current version)

If envault is not installed, install it:

Using Bun (recommended):

bun install -g envault-manager

Using npm:

npm install -g envault-manager

Verify installation:

# Should show version number
envault --version

# Should show help menu
envault --help

When to Use

Use envault when:

User asks to "set up environment variables" for a project
User wants to manage secrets across dev/staging/prod environments
User needs to copy variables between projects
User has existing .env files to import into centralized management
User wants to view or modify environment variables without editing files directly
User needs to sync environment variables across team or AI agent sessions

Quick Reference

Command	Purpose	Example
`envault project list`	List all tracked projects	`envault project list --json`
`envault env list`	List environments in current or specified project	`envault env list --project backend`
`envault var list`	List variables (with partial value display)	`envault var list --env prod`
`envault var get <KEY>`	Get full value of a variable	`envault var get DATABASE_URL`
`envault var set <KEY>`	Set variable (interactive/secure mode)	`envault var set API_KEY --env prod`
`envault var unset <KEY>`	Remove a single variable	`envault var unset OLD_KEY`
`envault var clear`	Remove all variables (with confirmation)	`envault var clear --env dev --yes`
`envault var copy <project>`	Copy variables from another project	`envault var copy backend --from-env prod --env staging`
`envault sync`	Sync store → project (write .env files)	`envault sync`
`envault sync --from project`	Sync project → store (import .env files)	`envault sync --from project`

Environment Mapping

Envault maps .env files to environment names:

File	Environment Name
`.env`	`default`
`.env.dev`	`dev`
`.env.prod`	`prod`
`.env.staging`	`staging`
`.env.<custom>`	`<custom>`

Important notes:

Default environment: When --env flag is omitted, envault uses default environment (mapped to .env file)
Custom environments: ANY .env.<name> file creates a <name> environment (e.g., .env.production → production env, not prod)
Recommended naming: Use short, simple names (dev, prod, staging) to avoid confusion

Command Details

Project Commands

`envault project list`

List all tracked projects in the database.

# Human-readable format
envault project list

# JSON format
envault project list --json

Output: Shows project name and absolute path for each tracked project.

Environment Commands

`envault env list`

List environments for current repo or a specific project.

# Current repo
envault env list

# Specific project by name
envault env list --project backend

# JSON output
envault env list --json

Flags:

--project <name> or -p <name>: Target a tracked project by name
--json: Output as JSON array

Variable Commands

`envault var list`

List all variables with partial value display (first4...last4 for security).

# Current repo, all environments
envault var list

# Specific project
envault var list --project backend

# Filter by environment
envault var list --env prod

# Combine filters with JSON output
envault var list --project frontend --env staging --json

Flags:

--project <name> or -p <name>: Target a tracked project
--env <env>: Filter by environment
--json: Output as JSON

Output format: Variables grouped by environment, values shown as xxxx...xxxx (masked).

`envault var get <KEY>`

Retrieve the full, unmasked value of a variable (prints to stdout).

# Get from default environment
envault var get DATABASE_URL

# Get from specific environment
envault var get API_KEY --env prod

Use case: Piping values to other commands or viewing full secrets.

Security note: Output goes to stdout, so avoid logging or displaying in insecure contexts.

`envault var set <KEY>`

Add or update an environment variable.

Interactive mode (RECOMMENDED for secrets):

# Hidden input prompt (value NOT in shell history)
envault var set API_KEY

# Multi-line value (certificates, private keys)
envault var set SSL_CERT --multiline

Non-interactive mode (for non-sensitive values only):

# Positional value (WARNING: appears in shell history)
envault var set DEBUG true

# Flag-based value (WARNING: appears in shell history)
envault var set PORT --value 3000

With environment:

# Set in production environment
envault var set DATABASE_URL --env prod

Behavior:

If variable exists, prompts for overwrite confirmation
Automatically creates project if not tracked yet
Writes to corresponding .env file immediately
Shows warning when using non-interactive mode

Flags:

--env <env>: Target environment (default: default)
--value <value>: Non-interactive value (avoid for secrets)
--multiline: Enable multi-line input (Ctrl+D to finish)

`envault var unset <KEY>`

Remove a single variable from an environment.

# Unset from default environment (with confirmation)
envault var unset OLD_API_KEY

# Unset from specific environment
envault var unset TEMP_TOKEN --env staging

Behavior:

Prompts for confirmation before deletion
Updates corresponding .env file
Fails if variable doesn't exist

`envault var clear`

Remove all variables from a project or environment.

# Clear all environments in current repo (with confirmation)
envault var clear

# Clear specific environment only
envault var clear --env dev

# Clear without confirmation
envault var clear --env test --yes

# Clear variables in a tracked project (store only)
envault var clear --project old-app --yes

Flags:

--project <name> or -p <name>: Target a tracked project (store only; doesn't update .env files)
--env <env>: Clear specific environment only
--yes or -y: Skip confirmation prompt

Important: When using --project, only the database is modified. Run envault sync in that project directory to update .env files.

`envault var copy <fromProject>`

Copy variables from another tracked project into the current repository.

Copy all variables (preserves environments):

# Copy all variables from all environments
envault var copy backend

# Copy all from specific source environment to same environment
envault var copy backend --from-env prod

Copy specific variable:

# Auto-detect which environment contains the key
envault var copy backend DATABASE_URL

# Copy from specific source to target environment
envault var copy backend DATABASE_URL --from-env prod --env staging

Flags:

--from-env <env>: Source environment (default: all environments or auto-detect)
--env <env> or --to-env <env>: Target environment (default: same as source)

Behavior:

Prompts for overwrite if variable exists in target
Automatically creates target project if not tracked
Updates corresponding .env files in current repo
Handles multiple projects with same name (prompts to select)

Sync Commands

`envault sync`

Sync between database (store) and project files.

Default: Store → Project (write .env files from database):

envault sync

Reverse: Project → Store (import .env files into database):

envault sync --from project

Direction:

Default (envault sync): Reads variables from database and writes to .env* files in current repo
--from project: Reads .env* files from current repo and imports into database

Use cases:

Store → Project: After copying variables, updating from another machine, or restoring from database
Project → Store: Initial import of existing .env files, or after manually editing files

Behavior:

Discovers all .env* files in git repository root
Maps files to environments (.env → default, .env.dev → dev, etc.)
Validates .env syntax before importing
Fails if parse errors detected (with line number and message)

Common Workflows

Setting up a new project

cd my-new-project
git init  # Required

# Add variables interactively (secure)
envault var set DATABASE_URL
envault var set API_KEY
envault var set JWT_SECRET

# Check what was created
envault var list
cat .env  # Variables now in .env file

Managing multiple environments

# Set up development
envault var set DATABASE_URL --env dev
envault var set DEBUG --value true --env dev

# Set up production
envault var set DATABASE_URL --env prod
envault var set DEBUG --value false --env prod

# List all environments
envault env list

# View production variables
envault var list --env prod

Copying variables between projects

cd my-frontend

# Copy all variables from backend
envault var copy backend

# Copy specific variable
envault var copy backend API_BASE_URL

# Copy prod to staging
envault var copy backend --from-env prod --env staging

Migrating existing .env files

cd existing-project

# Import all .env* files into database
envault sync --from project

# Verify import
envault var list

Working with tracked projects remotely

# From any directory, list variables in another project
envault var list --project backend --env prod

# Clear variables in a different project
envault var clear --project old-project --yes

# Note: .env files only update when you run sync IN that project directory

Security Best Practices

DO:

✅ Use interactive mode for secrets: envault var set API_KEY (no value arg)
✅ Use --multiline for certificates and multi-line secrets
✅ Use var get output in pipes carefully (avoid logging)
✅ Rely on filesystem permissions (database is chmod 600)

DON'T:

❌ Use envault var set KEY value for secrets (appears in shell history)
❌ Use --value flag for sensitive data
❌ Treat envault as encryption (it's plaintext storage)
❌ Commit .env files to git (envault doesn't prevent this)

Important: Envault is NOT a secrets management tool like HashiCorp Vault or AWS Secrets Manager. It stores values as plaintext (same as .env files) and relies on filesystem permissions for security. Its value is in centralized management and workflow improvement, not encryption.

Common Mistakes

Mistake	Fix
Using envault without checking if installed	Always run `envault --version` first. If not found, install with `bun install -g envault-manager`
Running outside git repo	Run `git init` first - envault requires git for project detection
Wrong sync direction	`envault sync` = store→project (default). Use `--from project` to import files
Environment name confusion	Use simple names: `dev`, `prod`, `staging` (not `development`, `production`)
Expecting `.env.production`	File should be `.env.prod` (environment name, not full word)
Using `--project` with `var set`	`var set` only works in current repo. `cd` to target project first
Forgetting `--env` flag	Defaults to `default` environment (`.env` file)
Overwrite without confirmation	Most commands prompt for confirmation; use `--yes` to skip (use carefully)
Shell history exposure	Use interactive mode (no value arg) to avoid secrets in history
Clearing wrong environment	Double-check `--env` flag before confirming `var clear`

Error Messages

Error	Meaning	Solution
`command not found: envault`	Envault is not installed on the system	Install with `bun install -g envault-manager`, then verify with `envault --version`
`Error: Not in a git repository`	Current directory is not in a git repo	Run `git init` or `cd` to a git repository
`Error: Project not tracked yet`	Project not in database	Run `envault var set <KEY>` or `envault sync --from project` to initialize
`Error: Variable 'KEY' not found`	Variable doesn't exist in specified environment	Check with `envault var list` or set with `envault var set`
`Error: Project 'name' not found`	No tracked project with that name	Check `envault project list` for available projects
`Error: Failed to parse .env`	Syntax error in .env file	Fix syntax error at reported line number before syncing

JSON Output

Many commands support --json flag for programmatic use:

# Get structured project data
envault project list --json

# Get environment list as array
envault env list --json

# Get variables as structured data
envault var list --json

Use case: Parsing output in scripts, CI/CD pipelines, or when building tools on top of envault.

Project Detection

Envault automatically identifies projects by their git repository root (absolute path). This means:

Same project, different machines: May have different absolute paths (considered different projects)
Multiple projects, same name: Envault prompts you to select which one
Project tracking: Happens automatically on first var set or sync --from project

To work across machines, use envault sync --from project to re-import on each machine, or use the var copy command to share variables between tracked projects.