Quickstart

This guide takes you from an empty account to pulling secrets on your laptop and in CI.

1. Create an account and a workspace

1. Sign up at envpass.dev with Google or with email and password.
2. Verify your email with the 6-digit code.
3. Create a workspace, for example acme. A new workspace has one environment, prod.

2. Add environments

Open Environments and add the ones you use, for example dev and staging. Turn on Allow personal overrides for dev if each developer should be able to point it at their own local services.

3. Create a project and services

A project is usually one repository. Create one (for example shop), then add a service for each deployable part under Project → Settings, for example api, web and worker.

4. Import your existing .env file

Open the project, pick an environment and a layer (Shared or a service), click Import .env, and paste or drop your file. The preview shows which keys are new, changed or identical before anything is saved.

5. Pull on your laptop

bunx envpass-cli login                         # opens your browser to approve
bunx envpass-cli link -w acme -p shop -e dev   # writes .envpass.json
bunx envpass-cli pull                          # writes .env
bunx envpass-cli run -- bun dev                # or inject without a file

Python users can run the same commands with uvx envpass-cli.

.envpass.json only contains slugs, never secrets, so it is safe to commit:

{
  "workspace": "acme",
  "project": "shop",
  "environment": "dev"
}

6. Pull in CI

Create a service token under Project → Tokens, scoped to the environments the job needs. Store it as a CI secret named ENVPASS_TOKEN, then:

npx envpass-cli pull -e prod -o .env

A service token already knows its workspace and project, so only the environment is required.

7. Invite your team

Invite people to the whole workspace under Members, or share a single project under Project → Access. Pick a role for each person; see Access control.