Overview
The validate_env_file tool validates a specific .env file against the codebase requirements. It identifies:
- Variables in the file that code never uses
- Variables code needs that aren’t in the file
- Variables with empty or placeholder values
Parameters
Path to the .env file to validate (relative to project or absolute).
Path to the project directory. Defaults to current working directory.
Response
Whether the env file passes validation (true if no failures)
Relative path to the validated env file
Validation results grouped by status
Variables that passed validation
Variable value (truncated if > 20 chars)
Variables with warnings
Description of the warning
Variable value (if applicable)
Variables that failed validation
Description of the failure
Variable value (if applicable)
Summary statistics
Total variables in the env file
Number of variables that passed
Variables in file but never used in code
Variables used in code but missing from file
Scan metadata
Absolute path to the scanned project
Whether the scan used cached results
Scan duration in milliseconds
Example Response
{
"valid": false,
"envFilePath": ".env.production",
"results": {
"passed": [
{
"variable": "DATABASE_URL",
"status": "pass",
"value": "postgresql://user:p..."
},
{
"variable": "REDIS_URL",
"status": "pass",
"value": "redis://localhost:..."
}
],
"warnings": [
{
"variable": "LEGACY_API_KEY",
"status": "warning",
"issue": "Defined in env file but never used in code",
"suggestion": "Remove if not needed, or verify it's used indirectly",
"value": "sk_test_abc123..."
},
{
"variable": "OPTIONAL_FEATURE",
"status": "warning",
"issue": "Used in code but missing from env file (has default)",
"suggestion": "Consider adding explicitly for clarity"
}
],
"failed": [
{
"variable": "API_KEY",
"status": "fail",
"issue": "Used in code but missing from env file",
"suggestion": "Add this variable to your env file"
},
{
"variable": "SECRET_KEY",
"status": "fail",
"issue": "Placeholder value detected",
"suggestion": "Replace with actual production value",
"value": "your-secret-here"
},
{
"variable": "SMTP_PASSWORD",
"status": "fail",
"issue": "Empty value",
"suggestion": "Set a valid value or remove if not needed",
"value": "(empty)"
}
]
},
"summary": {
"total": 7,
"passed": 2,
"warnings": 2,
"failed": 3,
"unusedInFile": 1,
"missingFromFile": 1
},
"metadata": {
"projectPath": "/Users/dev/my-project",
"scannedFiles": 156,
"cacheHit": false,
"duration": 212
}
}
Usage Example
AI assistants can validate environment files before deployment:
{
"name": "validate_env_file",
"arguments": {
"envFilePath": ".env.production",
"projectPath": "/path/to/project"
}
}
{
"name": "validate_env_file",
"arguments": {
"envFilePath": ".env"
}
}
Validation Rules
The tool checks for these common issues:
Failed Validations
- Missing from file: Variable used in code but not present in the env file
- Empty value: Variable defined but has no value
- Placeholder value: Contains placeholder text like “your-key-here”, “changeme”, “xxx”, etc.
Warnings
- Unused in file: Variable defined in env file but never used in code
- Missing with default: Variable used in code but not in file (has default value)
Placeholder Detection
The following patterns are detected as invalid placeholder values:
changemeyour-key, your-token, your-secret, your-passwordxxx (multiple x’s)todo, fixmereplace-me, replacemeplaceholder<...> or [...] bracketsexample
Use Cases
- Pre-Deployment: Validate production env files before deploying
- Environment Setup: Ensure developers have all required variables configured
- CI/CD: Automated validation in continuous integration pipelines
- Security: Detect placeholder values that shouldn’t be in production
- Cleanup: Identify unused variables that can be removed
