use-env

use-env > use_env > providers > tests > .github > docs > examples

Summary

Environment file processor with extensible secret providers.

use-env is a CLI tool for developers that processes environment files with secret references and resolves them from various providers (vault, environment variables, files, etc.).

Features

• Extensible Provider System: Add custom providers for any secret source
• Built-in Providers: Support for environment variables, files, and trusted shell commands (no external dependencies)
• Optional Cloud Providers: Azure, AWS, GCP, HashiCorp Vault, 1Password (install only what you need)
• Configuration: YAML-based configuration for custom providers
• Type Safety: Written in Python with full type annotations
• Test Coverage: Comprehensive test suite

Installation

# Core package only (env and file providers)
pip install env-use

# Or using uv
uv pip install env-use

Optional Cloud Providers

Install only the providers you need:

# Azure Key Vault (Python SDK)
pip install env-use[azure]

# AWS Secrets Manager
pip install env-use[aws]

# Google Cloud Secret Manager
pip install env-use[gcp]

# HashiCorp Vault
pip install env-use[vault]

# 1Password Connect
pip install env-use[1password]

# All cloud providers
pip install env-use[all]

Quick Start

Basic Usage

# Process .env.dev and output .env
use-env .env.dev

# Specify output file
use-env .env.prod -o .env.production

# List available providers
use-env --list-providers

# Show detailed usage guidance for an LLM
use-env --llm-help

Environment File Example

Create a .env.dev file:

# Regular values
DATABASE_HOST=localhost
DATABASE_PORT=5432

# Environment variable reference
API_KEY=${env:MY_API_KEY}

# File-based secret (Docker secrets, etc.)
DB_PASSWORD=${file:/run/secrets/db_password}

# Execute a trusted shell command and use its stdout
GREETING=${! echo "Hello" }

# Azure Key Vault (requires env-use[azure])
# Format: ${azure-keyvault:<vault_name>/<secret_name>}
SECRET_KEY=${azure-keyvault:my-keyvault/db-password}

# AWS Secrets Manager (requires env-use[aws])
# Format: ${aws-secrets:<region>/<secret_name>}
DB_PASSWORD=${aws-secrets:us-east-1/my-app/database}

# GCP Secret Manager (requires env-use[gcp])
# Format: ${gcp-secrets:<project_id>/<secret_name>}
API_KEY=${gcp-secrets:my-project/api-key}

# HashiCorp Vault (requires env-use[vault])
# Format: ${vault:<mount_point>/<path>}
DB_PASSWORD=${vault:secret/my-app/database}

# 1Password (requires env-use[1password])
# Format: ${1password:<vault_id>/<item_id>/<field>}
API_KEY=${1password:vault-id/item-id/api-key}

Run the tool:

use-env .env.dev

This will create a .env file with all references resolved.

Piping Support

The tool supports piping for flexible workflows:

# Pipe input from stdin, output to stdout
cat .env.dev | use-env

# Pipe input, save output to file
cat .env.dev | use-env > .env

# Pipe output to another command
use-env .env.prod | grep DB_HOST

# Chain with other tools
cat .env.staging | use-env | jq '.DATABASE_'

When input comes from stdin, output automatically goes to stdout. This enables standard Unix workflows.

Core Providers (No Extra Dependencies)

Environment Provider (env)

Reference environment variables:

API_KEY=${env:API_KEY}

File Provider (file)

Read secrets from files:

# Absolute path
DB_PASSWORD=${file:/run/secrets/db_password}

# Relative path (relative to config or current directory)
API_KEY=${file:./secrets/api_key.txt}

Shell Provider (shell)

Execute a trusted shell command and use its trimmed standard output:

GREETING=${! echo "Hello" }
CURRENT_BRANCH=${shell:git branch --show-current}

Shell references inherit the current environment and working directory and run with the permissions of the use-env process. Commands have a default 30-second timeout, and non-zero exit statuses fail resolution. Only use shell references with trusted input files.

Optional Cloud Providers

Azure Key Vault (azure-keyvault)

Requires: pip install env-use[azure]

# Format: ${azure-keyvault:<vault_name>/<secret_name>}
DB_PASSWORD=${azure-keyvault:my-keyvault/db-password}

Configuration (in .use-env.yaml):

providers:
  - name: azure
    type: azure-keyvault
    enabled: true
    config:
      tenant_id: "your-tenant-id"  # Optional, uses default credential
      client_id: "your-client-id"  # Optional
      client_secret: "your-secret" # Optional

AWS Secrets Manager (aws-secrets)

Requires: pip install env-use[aws]

# Format: ${aws-secrets:<region>/<secret_name>}
DB_PASSWORD=${aws-secrets:us-east-1/my-app/database}

Configuration:

providers:
  - name: aws
    type: aws-secrets
    enabled: true
    config:
      region: "us-east-1"           # Optional, uses default session
      profile: "my-aws-profile"     # Optional

GCP Secret Manager (gcp-secrets)

Requires: pip install env-use[gcp]

# Format: ${gcp-secrets:<project_id>/<secret_name>}
API_KEY=${gcp-secrets:my-project/api-key}

Configuration:

providers:
  - name: gcp
    type: gcp-secrets
    enabled: true
    config:
      project_id: "my-gcp-project"  # Optional, uses default

HashiCorp Vault (vault)

Requires: pip install env-use[vault]

# Format: ${vault:<mount_point>/<path>}
DB_PASSWORD=${vault:secret/my-app/database}
DB_HOST=${vault:secret/my-app/host}  # Returns specific field if secret is JSON

Configuration:

providers:
  - name: vault
    type: vault
    enabled: true
    config:
      url: "http://127.0.0.1:8200"  # Optional, uses VAULT_ADDR env var
      token: "your-vault-token"     # Optional, uses VAULT_TOKEN env var
      namespace: "your-namespace"   # Optional, for Enterprise Vault
      mount_point: "secret"         # Optional, default mount point

1Password Connect (1password)

Requires: pip install env-use[1password]

# Format: ${1password:<vault_id>/<item_id>/<field>}
API_KEY=${1password:vault-uuid/item-uuid/api-key}

Configuration:

providers:
  - name: onepassword
    type: 1password
    enabled: true
    config:
      connect_url: "http://localhost:8080"  # Optional, uses OP_CONNECT_HOST
      connect_token: "your-token"           # Optional, uses OP_CONNECT_TOKEN

Configuration

Create a .use-env.yaml file to configure providers:

providers:
  - name: azure
    type: azure-keyvault
    enabled: true
    config:
      tenant_id: "your-tenant-id"

  - name: aws
    type: aws-secrets
    enabled: true
    config:
      region: "us-east-1"

options:
  strict: true
  verbose: 1

Adding Custom Providers

See Provider Development Guide for detailed instructions.

Documentation

• Architecture - Internal design and components
• Provider Development - Guide for creating custom providers
• Usage Guide - Detailed usage instructions

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=use_env

# Run specific test file
pytest tests/test_providers.py

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

Pull Requests

• Runs on Python 3.12 and 3.13
• Ruff linting and formatting checks
• MyPy type checking
• Pytest with coverage
• Coverage uploaded to Codecov

Releases

• Automatically versions using python-semantic-release
• Maintains a release PR branch from main/master
• Pushes a new version tag when a release PR is merged
• Publishes to PyPI and creates a GitHub Release on version tags

Commit Convention

This project uses Conventional Commits:

feat: add new provider
fix: resolve caching issue
docs: update documentation

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details.