DevVault is a command-line developer experience layer for HashiCorp Vault. It lets local applications consume secrets at runtime without committing .env files, passwords or tokens to the project repository.

DevVault is a CLI, not an application framework or a replacement for HashiCorp Vault. Vault remains the source of truth for secrets, while DevVault prepares the local environment, resolves project environments and injects mapped secrets into a child process.

Why DevVault

• local Vault bootstrap through devvault start;
• automatic local initialization and unseal for the owned development Vault;
• project and environment isolation;
• runtime secret injection without creating .env files;
• OS keyring sessions for developer authentication;
• safe status and diagnostic commands;
• explicit protection for sensitive environments.

Requirements

• Node.js 20 or newer;
• Docker Engine or Docker Desktop with Docker Compose;
• Linux or WSL2 for the validated MVP scope;
• an available OS keyring for developer sessions;
• network access to npm during installation.

Native Windows, live remote Vault and Docker Desktop-specific behavior require additional validation in this MVP.

Platform support

| Platform | Status | |---|---| | Linux | ✅ Supported and tested | | WSL2 | ⚠️ Tested with limitations | | macOS | ⚪ Unverified | | Native Windows | ❌ Unsupported | | PowerShell → WSL | ⚠️ Tested with limitations |

Installation

npm install -g @fean-developer/devvault-cli
devvault --version
devvault --help

First project

From the root of an application project:

cd ~/my-project
devvault init-project --environment development
devvault environment set development
devvault start

devvault start prepares the owned local Vault automatically. The developer does not need to create, copy or enter a root token or unseal key.

During startup, the CLI displays progress for the local environment, Vault and secret storage. Failures show the reason and suggest devvault doctor.

Store application secrets through hidden prompts:

devvault secret set database.username
devvault secret set database.password

Run the application with configured secrets:

devvault run -- npm start

No .env file is created.

Environments

Environment Context

The active environment is the environment DevVault uses by default for project secret operations. Select it persistently from the project root:

devvault environment set development

This writes local context metadata to .devvault/context.json:

{
  "environment": "development"
}

The context file contains only the selected environment. It is not a secret store; secrets remain in Vault.

Subsequent secret get, secret list, secret set, secret delete, and run commands use the active environment unless given a command-scoped override.

devvault environment set <env>
            |
            v
    persistent context
            |
            v
   subsequent commands

--environment <env>
            |
            v
   current command only
            |
            v
   context remains unchanged

Use --environment <name> to target another configured environment for one invocation. It does not change the active context.

# Select development as the active environment.
devvault environment set development

# Uses development.
devvault secret get database.url

# Uses staging only for this command.
devvault secret get database.url --environment staging

# The active environment is still development.
devvault status

DevVault does not silently assume development. When no environment is selected, commands requiring project configuration report No environment selected. and, when configured environments exist, list them and direct you to devvault environment set <name>. Use devvault environment set <name> to intentionally change the persistent active environment.

devvault init-project --environment development
devvault init-project --environment production
devvault environment set development
devvault environment current
devvault environment list

Use another environment for one command without changing the active context:

devvault secret list --environment production
devvault run --environment production -- npm start

Supported applications

DevVault can run any local command that reads configuration from environment variables. It is not limited to Node.js.

| Application type | Example | | --- | --- | | Node.js / JavaScript / TypeScript | devvault run -- npm start | | Python | devvault run -- python app.py | | Go | devvault run -- ./my-service | | Java / Spring Boot | devvault run -- java -jar app.jar | | .NET | devvault run -- dotnet run | | Ruby / Rails | devvault run -- bundle exec rails server | | PHP / Laravel | devvault run -- php artisan serve | | Shell scripts | devvault run -- ./deploy-local.sh | | Database and migration CLIs | devvault run -- npx prisma migrate dev | | Docker compose | devvault run -- docker compose up -d |

The application must already know which environment variable names to read. Configure mappings in the environment YAML:

runtime:
  mappings:
    DATABASE_URL: database.url
    DATABASE_PASSWORD: database.password

• Configure docker compose

Never do that, this is insecure

 backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
      target: production
    container_name: myContainerName
    restart: unless-stopped
    env_file:
      - ./backend/.env.docker # don't do that
    environment:
      ...

Use this

 backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
      target: production
    container_name: myContainerName
    restart: unless-stopped
    environment:
      DATABASE_URL: ${DATABASE_URL}           # Your secret database.url 
      DATABASE_PASSWORD: ${DATABASE_PASSWORD} # Your secret database.password

Common commands

devvault start
devvault status
devvault doctor
devvault secret set <key>
devvault secret get <key>
devvault secret list
devvault secret delete <key> --yes
devvault run -- <command> [args...]
devvault logout

Create an additional local developer identity:

devvault user create --username <name>
devvault logout
devvault login --username <name>

Documentation

• Guia completo em português
• Release notes

Security and MVP limitations

Secrets stay in Vault and are resolved only when a process starts. Do not put tokens, passwords or secret values in project files, command arguments, logs or Git.

This is a pre-1.0 MVP. A compromised workstation, Docker daemon or local user may access local secrets. Read the release notes before use.

Uninstall

npm uninstall -g @fean-developer/devvault-cli