OneDoTenv

The Ultimate .env File Manager: Discover, categorize, validate, and track environment variables across all your projects.

OneDoTenv is a comprehensive Python CLI tool that helps developers manage scattered environment variables across multiple projects. It intelligently categorizes API keys, detects security issues, tracks changes over time, and consolidates everything into organized, secure formats.

Why OneDoTenv?

Ever found yourself:

🔍 Searching through dozens of projects for "that one API key"?
🤔 Wondering which .env file has the latest Stripe key?
😰 Using placeholder values like change-me in production?
📝 Manually tracking which keys need rotation?
🔐 Storing API keys in plaintext state files?

OneDoTenv solves all of this with intelligent scanning, automatic categorization, security validation, and hash-based state tracking.

Features

🔍 Smart Discovery

Recursive scanning across unlimited directories
Pattern matching for .env, .env.local, .env.production, and custom patterns
Automatic conflict resolution (newest version wins)
Error recovery with detailed reporting

🗂️ Intelligent Categorization

10 built-in categories: AI APIs, databases, auth, cloud, payment, email, storage, analytics, monitoring, search
35+ provider patterns: OpenAI, Anthropic, Stripe, AWS, PostgreSQL, MongoDB, and more
70+ regex patterns for accurate detection
Custom pattern support via runtime API or JSON config

✅ Security Validation

Format checking against known patterns (OpenAI, Anthropic, Stripe, AWS, GitHub, Google)
Weak value detection: placeholders, defaults, empty values
Security warnings: quotes, whitespace, unrecognized keys
Best practices enforcement

📊 State Management

SHA256 hash-based storage (never stores plaintext values)
Change tracking: added, removed, modified keys
History logs with timestamped entries
Automatic backups before every save
Secure permissions (600 - owner read/write only)

📤 Multiple Export Formats

Legacy format: Compatible with original scanENV.py
Categorized format: Grouped by category and provider
JSON format: Machine-readable for integrations
Filtered exports: By category or provider

Quick Start

Installation

# Install from PyPI (coming soon)
pip install onedotenv

# Or install from source
git clone https://github.com/deesatzed/OneDoTenv.git
cd OneDoTenv
pip install -e .

Basic Usage

# Scan your projects directory
onedotenv scan ~/projects

# Scan with validation
onedotenv scan ~/projects --validate

# Show all AI API keys
onedotenv categorize --category ai_api

# Export to consolidated file
onedotenv export --format categorized -o .env.consolidated

# View state and history
onedotenv state info
onedotenv state history

Installation

Prerequisites

Python 3.8 or higher
pip

Install from Source

# Clone the repository
git clone https://github.com/deesatzed/OneDoTenv.git
cd OneDoTenv

# Install in development mode
pip install -e .

# Verify installation
onedotenv --version

Install from PyPI (Coming Soon)

pip install onedotenv

Usage Guide

Commands Overview

OneDoTenv provides 5 main commands:

Command	Purpose	Example
`scan`	Discover and scan .env files	`onedotenv scan ~/projects --validate`
`validate`	Check key formats and security	`onedotenv validate`
`categorize`	View keys by category/provider	`onedotenv categorize --category ai_api`
`state`	Manage state and view history	`onedotenv state info`
`export`	Export keys in various formats	`onedotenv export --format json`

Detailed Examples

Scanning Projects

# Basic scan
onedotenv scan ~/projects

# Scan with custom patterns
onedotenv scan ~/work --patterns .env .env.production .env.staging

# Scan and validate
onedotenv scan . --validate

# Scan without saving state (testing)
onedotenv scan ~/projects --no-save-state

Categorizing Keys

# View all keys grouped by category
onedotenv categorize

# Filter by category
onedotenv categorize --category ai_api
onedotenv categorize --category database

# Filter by provider
onedotenv categorize --provider openai
onedotenv categorize --provider stripe

# JSON output for scripting
onedotenv categorize --format json

# Simple list format
onedotenv categorize --format list

Validating Keys

# Validate from state file
onedotenv validate

# Show valid keys too (not just invalid)
onedotenv validate --show-valid

# Validate during scan (recommended)
onedotenv scan ~/projects --validate

Note: Due to security (hash-based storage), validation from state only shows metadata. Use scan --validate to validate actual key values.

Exporting Keys

# Export in categorized format (default)
onedotenv export

# Export to file
onedotenv export --format categorized -o consolidated.env

# Export only AI API keys
onedotenv export --category ai_api

# Export only Stripe keys
onedotenv export --provider stripe

# Export in legacy format (compatible with scanENV v1.0)
onedotenv export --format legacy -o .env.consolidated

# Export as JSON
onedotenv export --format json -o keys.json

State Management

# View state information
onedotenv state info

# View change history
onedotenv state history

# Limit history entries
onedotenv state history --limit 5

# View changes since last scan (requires re-scan)
onedotenv state diff

Example Output

Scan with Validation

🔍 Scanning 3 path(s)...
✓ Scanned: /Users/dev/project1/.env
✓ Scanned: /Users/dev/project2/.env.local
✓ Scanned: /Users/dev/project3/.env

============================================================
📊 COLLECTION SUMMARY
============================================================
Files scanned: 3
Files failed: 0
Unique keys found: 12

📁 Keys by category:
  • ai_api: 3 key(s)
  • database: 2 key(s)
  • auth: 2 key(s)
  • payment: 1 key(s)
  • unknown: 4 key(s)

🔑 Keys by provider:
  • openai: 2 key(s)
  • anthropic: 1 key(s)
  • postgres: 2 key(s)
  • stripe: 1 key(s)
  • jwt: 2 key(s)
  • unknown: 4 key(s)
============================================================

🔐 Validating keys...

❌ Found 2 invalid key(s):

  PLACEHOLDER_API_KEY:
    • Value appears to be a placeholder

  WEAK_SECRET:
    • Value is a common default/weak value

📊 Validation: 10 valid, 2 invalid, 0 warnings

💾 State saved to .onedotenv_state.json
   • 12 key(s) added

Categorized View

📁 Keys by Category (12 total):

============================================================
AI_API
============================================================

  openai (2 key(s)):
    • OPENAI_API_KEY
      Source: /Users/dev/project1/.env
    • OPENAI_ORG_ID
      Source: /Users/dev/project1/.env

  anthropic (1 key(s)):
    • ANTHROPIC_API_KEY
      Source: /Users/dev/project2/.env.local

============================================================
DATABASE
============================================================

  postgres (2 key(s)):
    • DATABASE_URL
      Source: /Users/dev/project3/.env
    • POSTGRES_CONNECTION_STRING
      Source: /Users/dev/project3/.env

Supported Categories & Providers

Categories (10)

Category	Description	Example Keys
`ai_api`	AI/ML API keys	OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_KEY
`database`	Database connections	DATABASE_URL, POSTGRES_HOST, MONGODB_URI
`auth`	Authentication	JWT_SECRET, OAUTH_CLIENT_ID, SESSION_SECRET
`cloud`	Cloud providers	AWS_ACCESS_KEY, AZURE_KEY, GCP_PROJECT_ID
`payment`	Payment processors	STRIPE_SECRET_KEY, PAYPAL_CLIENT_ID
`email`	Email services	SENDGRID_API_KEY, MAILGUN_KEY
`storage`	Object storage	S3_BUCKET, R2_ACCESS_KEY
`analytics`	Analytics platforms	GA_TRACKING_ID, MIXPANEL_TOKEN
`monitoring`	Monitoring/logging	SENTRY_DSN, DATADOG_API_KEY
`search`	Search engines	ALGOLIA_API_KEY, ELASTICSEARCH_URL

Providers (35+)

AI/ML: OpenAI, Anthropic, Google AI, Cohere, Hugging Face Databases: PostgreSQL, MySQL, MongoDB, Redis, SQLite Cloud: AWS, Azure, GCP, Heroku, Vercel, Netlify, Railway Payment: Stripe, PayPal, Square Email: SendGrid, Mailgun, AWS SES, Postmark Storage: AWS S3, Cloudflare R2, Google Cloud Storage Analytics: Google Analytics, Mixpanel, Segment, Amplitude Monitoring: Sentry, Datadog, New Relic, LogRocket Search: Algolia, Elasticsearch, Typesense And many more...

Security Features

Hash-Based State Storage

OneDoTenv never stores plaintext API keys in state files. All values are SHA256 hashed:

{
  "OPENAI_API_KEY": {
    "name": "OPENAI_API_KEY",
    "value_hash": "5bebfec3fdd4e654ee8b8d3ca137476759a4e5e7b3861a8d56895896b2d650f6",
    "category": "ai_api",
    "provider": "openai"
  }
}

Secure File Permissions

All state and history files are automatically set to 600 (owner read/write only):

$ ls -la .onedotenv_state.json
-rw------- 1 user user 4096 Dec 31 12:00 .onedotenv_state.json

Validation Rules

OneDoTenv validates keys against known patterns:

OpenAI: sk-[a-zA-Z0-9]{48}, sk-proj-[a-zA-Z0-9_-]{48,}
Anthropic: sk-ant-[a-zA-Z0-9_-]{95,}
Stripe: sk_live_*, sk_test_*, pk_live_*, pk_test_*
AWS: AKIA[0-9A-Z]{16}
GitHub: ghp_[a-zA-Z0-9]{36}, gho_*, ghs_*
Google: AIza[0-9A-Za-z_-]{35}

Weak Value Detection

Automatically detects and warns about:

Placeholders: your-api-key, placeholder, change-me, replace-me
Defaults: default, secret, password, admin, root
Empty values: null, none, undefined, blank strings

Architecture

Package Structure

OneDoTenv/
├── src/onedotenv/
│   ├── cli/              # Command-line interface
│   ├── core/             # Core functionality
│   │   ├── scanner.py    # File scanning
│   │   ├── categorizer.py # Pattern matching
│   │   ├── validator.py  # Security validation
│   │   └── state.py      # State management
│   ├── models/           # Data models
│   └── utils/            # Utilities and patterns
├── tests/
│   ├── unit/            # 108 unit tests
│   └── fixtures/        # Test data
├── pyproject.toml       # Package configuration
└── README.md           # This file

Test Coverage

Total: 108 tests, all passing Core Coverage:

Scanner: 92% (132 statements, 27 tests)
Categorizer: 94% (102 statements, 27 tests)
State Manager: 91% (116 statements, 23 tests)
Validator: 100% (101 statements, 31 tests)

Extending OneDoTenv

Adding Custom Patterns

Runtime API

from onedotenv.core.categorizer import Categorizer

categorizer = Categorizer()
categorizer.add_custom_pattern(
    category='custom',
    provider='my_service',
    pattern=r'^MY_SERVICE_'
)

JSON Configuration

Create custom_patterns.json:

{
  "custom_category": {
    "my_provider": [
      "^MY_KEY_",
      "_MY_SUFFIX$"
    ]
  }
}

Load it:

categorizer._load_custom_patterns('custom_patterns.json')

Adding Validation Rules

Edit src/onedotenv/core/validator.py:

VALIDATION_RULES = {
    'my_provider': {
        'patterns': [r'^prefix-[a-z0-9]{32}$'],
        'min_length': 32,
        'prefix': 'prefix-',
    },
}

Best Practices

What to Commit

✅ DO commit:

pyproject.toml
README.md
.gitignore
Source code
Tests

❌ NEVER commit:

.env files (actual environment variables)
.onedotenv_state.json (contains hashed values)
.onedotenv_history/ (change logs)
Exported .env.consolidated files

Recommended .gitignore

# Environment files
.env
.env.*
*.env

# OneDoTenv files
.onedotenv_state.json
.onedotenv_state.backup_*
.onedotenv_history/
.env.consolidated

Security Workflow

Scan regularly:
```
onedotenv scan ~/projects --validate
```
Review warnings:
- Fix placeholder values
- Update weak secrets
- Rotate old keys
Track changes:
```
onedotenv state history
```

Export securely:

# Export only what you need
onedotenv export --category ai_api -o ai_keys.env

# Use immediately
source ai_keys.env

# Delete export
rm ai_keys.env

Troubleshooting

No keys found

Problem: "Unique keys found: 0"

Solutions:

Check file patterns: --patterns .env .env.local .env.production
Verify file naming (must match patterns exactly)
Ensure files aren't empty or all comments

Permission denied

Problem: "Permission denied: /path"

Solutions:

Run with appropriate permissions
Exclude system directories
Check directory ownership: ls -ld /path

State file corrupted

Problem: "State file corrupted"

Solutions:

Check backup files: .onedotenv_state.backup_*
Delete corrupted file: rm .onedotenv_state.json
Re-scan: onedotenv scan ~/projects

Wrong category

Problem: Key categorized incorrectly

Solutions:

Check pattern priority in source code
Add custom pattern for your use case
Open an issue with the key pattern

Roadmap

v2.1 (Q1 2025)

Connection testing (--test-connections)
Key rotation tracking
Multi-line value support (SSH keys, JWTs)

v2.2 (Q2 2025)

Interactive conflict resolution UI
YAML and TOML export formats
Environment-specific exports

v3.0 (Future)

Web UI for visualization
Plugin system
Integration with cloud secret managers

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Write tests for your changes (aim for >90% coverage)
Ensure all tests pass: pytest
Commit your changes: git commit -m "Add amazing feature"
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/OneDoTenv.git
cd OneDoTenv

# Install in development mode
pip install -e .

# Install dev dependencies
pip install pytest pytest-cov

# Run tests
pytest

# Run with coverage
pytest --cov=onedotenv --cov-report=term-missing

Code Style

Python 3.8+ type hints
Docstrings for all public methods
PEP 8 compliance
90% test coverage for new code

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Author: Created with Claude Code (Anthropic) Purpose: Defensive security tooling for environment variable management Inspiration: The pain of managing scattered API keys across dozens of projects

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Security: Report security issues privately to the repository owner

Acknowledgments

Built with Python and love for developer productivity
Tested with pytest
Inspired by the need for better .env management
Developed entirely using Claude Code

Made with ❤️ for developers who are tired of hunting for API keys

⭐ Star this repo if OneDoTenv helps you manage your environment variables!

Name		Name	Last commit message	Last commit date
src/scanenv		src/scanenv
tests		tests
.gitignore		.gitignore
BLOG.md		BLOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
MITIGATION_PLAN.md		MITIGATION_PLAN.md
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
scanENV.py		scanENV.py

Latest commit

History

Folders and files

Repository files navigation

OneDoTenv

Why OneDoTenv?

Features

🔍 Smart Discovery

🗂️ Intelligent Categorization

✅ Security Validation

📊 State Management

📤 Multiple Export Formats

Quick Start

Installation

Basic Usage

Installation

Prerequisites

Install from Source

Install from PyPI (Coming Soon)

Usage Guide

Commands Overview

Detailed Examples

Scanning Projects

Categorizing Keys

Validating Keys

Exporting Keys

State Management

Example Output

Scan with Validation

Categorized View

Supported Categories & Providers

Categories (10)

Providers (35+)

Security Features

Hash-Based State Storage

Secure File Permissions

Validation Rules

Weak Value Detection

Architecture

Package Structure

Test Coverage

Extending OneDoTenv

Adding Custom Patterns

Runtime API

JSON Configuration

Adding Validation Rules

Best Practices

What to Commit

Recommended .gitignore

Security Workflow

Troubleshooting

No keys found

Permission denied

State file corrupted

Wrong category

Roadmap

v2.1 (Q1 2025)

v2.2 (Q2 2025)

v3.0 (Future)

Contributing

Development Setup

Code Style

License

Credits

Support

Acknowledgments

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages