passenv 0.3.0

Load environment variables from pass entries

PassEnv

Load environment variables from pass entries seamlessly in your shell.

Features

• Secure: Leverages the existing pass password manager
• Simple: Load/unload environment variables with a single command
• Stateful: Tracks what's loaded and prevents conflicts
• Auto-completion: Tab completion for pass entries
• Shell Integration: Works with bash, zsh, fish, and more

Installation

Prerequisites

• pass must be installed and initialized
• Python 3.10 or higher

Install from PyPI

pip install passenv

Set up shell integration

After installation, run the setup command:

passenv install

This will add the necessary shell function and completion to your ~/.bashrc, ~/.zshrc, or specific shell rc file.

Usage

Basic Commands

# Load environment variables from a pass entry at database/envs
passenv load database/envs

# Check what's currently loaded
passenv status

# List available pass entries
passenv list

# Unload current environment
passenv unload

# Export as .env format (default)
passenv export database/envs

Pass Entry Format

Store your environment variables in pass entries using the KEY=VALUE format:

# Create a pass entry
pass edit database/envs

Example entry content:

DATABASE_URL=postgres://user:pass@localhost/mydb
API_KEY=secret123
DEBUG=false
# This is a comment
LOG_LEVEL=info

Advanced Usage

Environment Isolation

PassEnv automatically handles environment isolation:

• Loading a new set of environment variables automatically unloads the previous ones
• Tracks which variables were loaded to prevent conflicts
• Provides clear status information

Examples

Development Workflow

# Load development environment
passenv load myapp/development

# Run your application
python manage.py runserver

# Switch to staging environment
passenv load myapp/staging

# Deploy to staging
./deploy.sh

# Clean up
passenv unload

Basic Export Usage

# Export as .env format (default)
passenv export database/envs

# Export to different formats
passenv export database/envs --format yaml
passenv export database/envs --format json
passenv export database/envs --format csv
passenv export database/envs --format docker

# Save to file
passenv export database/envs --output .env
passenv export database/envs --format yaml --output config.yaml

Export Formats

.env format (default)

passenv export myapp/production

Output:

DATABASE_URL=postgres://user:pass@localhost/mydb
API_KEY=secret123
DEBUG=false
LOG_LEVEL=info

YAML format

passenv export myapp/production --format yaml

Output:

DATABASE_URL: postgres://user:pass@localhost/mydb
API_KEY: secret123
DEBUG: "false"
LOG_LEVEL: info

JSON format

passenv export myapp/production --format json

Output:

{
  "DATABASE_URL": "postgres://user:pass@localhost/mydb",
  "API_KEY": "secret123", 
  "DEBUG": "false",
  "LOG_LEVEL": "info"
}

CSV format

passenv export myapp/production --format csv

Output:

KEY,VALUE
DATABASE_URL,postgres://user:pass@localhost/mydb
API_KEY,secret123
DEBUG,false
LOG_LEVEL,info

Docker format

passenv export myapp/production --format docker

Output:

-e DATABASE_URL="postgres://user:pass@localhost/mydb" -e API_KEY="secret123" -e DEBUG="false" -e LOG_LEVEL="info"

Docker Integration Examples

# Export and use directly with docker run
docker run $(passenv export myapp/production --format docker) my-app:latest

# Save to file and use with docker-compose
passenv export myapp/production --output .env
docker-compose up

# Use with Kubernetes ConfigMap
passenv export myapp/production --format yaml --output configmap.yaml
kubectl create configmap app-config --from-file=configmap.yaml

Pass Entry Organization Suggestion

Organize your pass entries logically:

myapp/
├── development
├── staging
└── production

database/
├── local
├── staging
└── production

Environment Variable Format

• Comments: Lines starting with # are ignored
• Empty lines: Skipped automatically
• Format: KEY=VALUE (spaces around = are stripped)
• Quotes: Optional quotes around values are removed
• Variable names: Must be valid shell variable names ([A-Za-z_][A-Za-z0-9_]*)

Troubleshooting

Common Issues

Pass not found

Error: 'pass' command not found. Please install pass.

Install pass using your package manager:

# Ubuntu/Debian
sudo apt install pass

# macOS
brew install pass

# Arch Linux
sudo pacman -S pass

Pass not initialized

Error: Pass store not initialized.

Initialize your pass store:

pass init your-gpg-key-id

Entry not found

Error: Pass entry 'myapp/staging' not found.

Create the entry:

pass edit myapp/staging

Invalid variable format

Error: Invalid line 'malformed-line' in pass entry.

Check your pass entry format. Each line should be KEY=VALUE or a comment.

Getting Help

# Show help
passenv --help

# Show command-specific help
passenv load --help

Development

Local Development

# Clone the repository
git clone https://github.com/yourusername/passenv.git
cd passenv

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=passenv

# Run specific test file
pytest tests/test_parser.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• pass - The password manager this tool integrates with