dotman

A command-line tool for managing environment variables securely with password managers. Store, sync, and share environment variables across your team using your preferred secrets provider.

Features

• Secure Storage – Store environment variables in your password manager vault
• Bi-directional Sync – Push local changes to vault and pull updates from it
• Multi-environment Support – Manage dev, staging, production, and custom environments
• Password Manager Integration – Currently supports 1Password and Bitwarden, with an extensible provider system
• Load & Run – Load env vars and execute commands in one step

Installation

npm install -g dotman-cli

Or with your preferred package manager:

# pnpm
pnpm add -g dotman-cli

# yarn
yarn global add dotman-cli

# bun
bun add -g dotman-cli

Quick Start

1. Initialize a Project

Run the initialization wizard to set up your project with a password manager:

dotman init

This will:

• Prompt you to select a storage provider (currenlty 1Password or Bitwarden)
• Guide you through entering required credentials
• Create or update your .env file
• Create a project in your vault to store environment variables

2. Push Environment Variables

Push your local environment variables to the vault:

# Preview changes first
dotman push

# Apply changes to vault
dotman push --apply

3. Pull Environment Variables

Sync environment variables from the vault to your local .env file:

# Preview changes first
dotman pull

# Apply changes locally
dotman pull --apply

4. Run Commands with Loaded Environment

Load environment variables and run a command:

dotman load -- npm run dev
dotman load -- node server.js

Commands

dotman init

Initialize a new project with a password manager integration.

dotman init

The wizard will guide you through:

• Selecting a storage provider
• Configuring vault/project settings
• Setting up authentication tokens

dotman push

Push local environment variables to the vault.

# Preview what will be pushed
dotman push

# Push changes (for a specific environment)
dotman push -e dev --apply

Options:

• -e, --env <ENV> – Target environment (e.g., dev, stag, prod)
• -a, --apply – Apply the changes (without this flag, only shows a preview)

dotman pull

Pull environment variables from the vault to local .env file.

# Preview what will be pulled
dotman pull

# Pull changes (for a specific environment)
dotman pull -e prod --apply

Options:

• -e, --env <ENV> – Target environment
• -a, --apply – Apply the changes locally

dotman load

Load environment variables from .env files and run a command.

dotman load -- <command>

# Examples
dotman load -- npm run dev
dotman load -- python app.py
dotman load -e prod -- node server.js

Options:

• -e, --env <ENV> – Environment to load, default to "master"

dotman env

Manage environments.

dotman env list

List all available environments:

dotman env list

Output:

Available Environments:
  ★ master (.env) (current)
  • dev
  • prod

3 environments found

dotman env new <name>

Create a new environment:

dotman env new staging

This creates:

• A new .env.staging file with placeholders
• A corresponding project/section in your vault

dotman env use <name>

Switch to a different environment:

dotman env use production

Provider Setup

1Password

📖 Complete 1Password Setup Guide – Follow this step-by-step guide to set up 1Password Service Accounts.

Bitwarden

📖 Complete Bitwarden Setup Guide – Follow this step-by-step guide to set up Bitwarden Secrets Manager (Cloud or Self-hosted).

Environment Files

dotman uses a simple naming convention:

| File | Description | | ------------- | --------------------------------------- | | .env | Master environment with provider config | | .env.<name> | Any environment name you choose |

The part after .env. becomes the environment name. For example:

• .env → environment name is master
• .env.dev → environment name is dev
• .env.staging → environment name is staging
• .env.production → environment name is production
• .env.local-test → environment name is local-test

About the Master .env File

The master .env file primarily stores the configuration keys needed to connect to your secrets provider (like OP_SERVICE_ACCOUNT_TOKEN for 1Password or BWS_ACCESS_TOKEN for Bitwarden).

While you can add application-specific variables to the master .env file and they will be loaded alongside your environment-specific variables, it's recommended to create a separate environment (e.g., .env.dev, .env.local) for your application variables. This keeps things cleaner and makes it easier to:

• Manage different configurations per environment
• Share environment-specific secrets with your team via the vault
• Avoid confusion between provider config and app variables

Note: All .env* files should be added to .gitignore and never committed to version control.

Workflow Example

Here's a typical team workflow:

# Initial setup (one-time)
dotman init

# Create and switch to development environment
dotman env new dev
dotman env use dev

# During development
dotman pull --apply        # Get latest env vars
dotman load -- npm run dev # Run with loaded env

# Add new variables
echo "NEW_API_KEY=abc123" >> .env.dev
dotman push --apply        # Share with team

# Setup production (one-time)
dotman env new prod

# Deploy to production
dotman env use prod
dotman pull --apply
dotman load -- npm start

Security Notes

[!NOTE] Credential Security: The configuration variables (like OP_SERVICE_ACCOUNT_TOKEN, BWS_ACCESS_TOKEN, DOTMAN_PROJECT_NAME) stored in your .env file are never pushed to your secret vault. They remain local to your machine only. These credentials are automatically filtered out during dotman push operations.

• Never commit environment files – Add .env* to your .gitignore to exclude all env files (.env, .env.dev, .env.prod, etc.)
• Use service accounts – Create dedicated tokens with minimal permissions
• Rotate tokens regularly – Update your service account tokens periodically
• The provider tokens (like OP_SERVICE_ACCOUNT_TOKEN) are stored locally in your .env file

Development

# Install dependencies
pnpm install

# Run in development
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Format code
pnpm format

# Lint and fix
pnpm check:write

License

MIT