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

Or with your preferred package manager:

Quick Start

1. Initialize a Project

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

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:

3. Pull Environment Variables

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

4. Run Commands with Loaded Environment

Load environment variables and run a command:

Commands

dotman init

Initialize a new project with a password manager integration.

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.

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.

Options:

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

dotman load

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

Options:

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

dotman env

Manage environments.

dotman env list

List all available environments:

Output:

dotman env new <name>

Create a new environment:

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:

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:

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:

Security Notes

• 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

License

MIT