Skip to content
PassBox

Quickstart

Install the CLI

Section titled “Install the CLI”
Terminal window
npm install -g pabox

The package is named pabox on npm, but the binary command is passbox.

Your First Secret

Section titled “Your First Secret”

  1. Create an account

    Terminal window
    passbox login

    Enter your email and password. PassBox derives an encryption key from your password using Argon2id — this key never leaves your machine.

  2. Create a vault

    Terminal window
    passbox vault create my-app

    A vault is a collection of secrets. Each vault has its own encryption key.

  3. Store a secret

    Terminal window
    passbox set DATABASE_URL "postgres://user:pass@host:5432/db" --vault my-app

    The value is encrypted client-side with AES-256-GCM before being sent to the server.

  4. Retrieve the secret

    Terminal window
    passbox get DATABASE_URL --vault my-app

    Output: postgres://user:pass@host:5432/db

  5. List all secrets

    Terminal window
    passbox list --vault my-app

Run Your App with Secrets

Section titled “Run Your App with Secrets”

Inject secrets as environment variables into any command:

Terminal window
passbox run --vault my-app -- node server.js

This starts node server.js with all vault secrets available as process.env.DATABASE_URL, etc.

Work with .env Files

Section titled “Work with .env Files”

Push a local .env file to your vault:

Terminal window
passbox env push .env --vault my-app

Pull secrets into a .env file:

Terminal window
passbox env pull --vault my-app -o .env.local

Use Environments

Section titled “Use Environments”

Separate your secrets by environment (development, staging, production):

Terminal window
# Create environments
passbox environment create staging --vault my-app
passbox environment create production --vault my-app


# Store secrets in specific environments
passbox set DATABASE_URL "postgres://staging-host/db" --vault my-app --env staging
passbox set DATABASE_URL "postgres://prod-host/db" --vault my-app --env production


# Retrieve from a specific environment
passbox get DATABASE_URL --vault my-app --env production

Project Configuration

Section titled “Project Configuration”

Initialize a .passbox.json in your project directory to set defaults:

Terminal window
passbox init

This creates a config file so you don’t need to pass --vault every time:

{
  "vault": "my-app",
  "environment": "development"
}

Now you can simply run:

Terminal window
passbox get DATABASE_URL
passbox set API_KEY "sk-..."
passbox run -- npm start

Next Steps

Section titled “Next Steps”