Overview
The get_env_usage tool provides a comprehensive analysis of a single environment variable. It shows:
- Every place the variable is used in code
- What the code does with it
- Whether it has fallback values
- Full risk profile and issues
- Specific recommendations
Parameters
The name of the environment variable to analyze (case-insensitive)
Path to the project directory. Defaults to current working directory.
Response
Whether the variable was found in the project
Variable details (only present if found=true)
Variable name (uppercase)
Where the variable is defined
Relative path to the file
Whether this definition includes a default value
The default value (if hasDefault=true)
Where the variable is used (limited to first 20)
Relative path to the file
Code snippet showing usage
Whether this usage has a fallback value
The fallback value (if hasDefault=true)
Overall risk level: critical, high, medium, low, or info
Array of detected issues
Issue type (e.g., MISSING, UNDOCUMENTED)
Human-readable description
Specific fix recommendation
Usage summary
Total number of usages in code
Total number of definitions in .env files
Programming languages using this variable
Whether any usage has a default value
Whether documented in .env.example
Whether defined in any .env file
Whether defined in .env.example
Array of specific action recommendations
Scan metadata
Absolute path to the scanned project
Whether the scan used cached results
Scan duration in milliseconds
Example Response (Found)
{
"found": true,
"variable": {
"name": "API_KEY",
"definitions": [
{
"file": ".env",
"line": 12,
"language": "env",
"context": "API_KEY=sk_test_abc123",
"hasDefault": false
},
{
"file": ".env.example",
"line": 8,
"language": "env",
"context": "API_KEY=your-api-key-here",
"hasDefault": false
}
],
"usages": [
{
"file": "src/api/client.ts",
"line": 15,
"language": "typescript",
"context": "const apiKey = process.env.API_KEY;",
"hasDefault": false
},
{
"file": "src/services/external-api.ts",
"line": 28,
"language": "typescript",
"context": "headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }",
"hasDefault": false
},
{
"file": "src/config/api.ts",
"line": 5,
"language": "typescript",
"context": "apiKey: process.env.API_KEY || 'default-key'",
"hasDefault": true,
"defaultValue": "default-key"
}
],
"riskLevel": "high",
"issues": [
{
"type": "INCONSISTENT_DEFAULT",
"message": "Variable has a default value in some usages but not others",
"recommendation": "Ensure consistent fallback handling across all usages of API_KEY"
}
],
"summary": {
"totalUsages": 8,
"totalDefinitions": 2,
"languages": ["typescript"],
"hasDefault": true,
"isDocumented": true,
"definedInEnvFile": true,
"definedInExample": true
},
"recommendations": [
"Remove default value 'default-key' from src/config/api.ts as it may mask missing configuration",
"Ensure API_KEY is set in all environments before deployment"
]
},
"metadata": {
"projectPath": "/Users/dev/my-project",
"scannedFiles": 156,
"cacheHit": false,
"duration": 201
}
}
Example Response (Not Found)
{
"found": false,
"metadata": {
"projectPath": "/Users/dev/my-project",
"scannedFiles": 156,
"cacheHit": false,
"duration": 187
}
}
Usage Example
Analyze a specific variable:
{
"name": "get_env_usage",
"arguments": {
"variableName": "API_KEY",
"projectPath": "/path/to/project"
}
}
{
"name": "get_env_usage",
"arguments": {
"variableName": "api_key"
}
}
Code Context Examples
The context field shows actual code snippets:
// Direct access
"const apiKey = process.env.API_KEY;"
// With default value
"const port = process.env.PORT || 3000;"
// In object
"headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }"
// With validation
"if (!process.env.DATABASE_URL) throw new Error('Missing DATABASE_URL');"
// Destructuring
"const { API_KEY, API_SECRET } = process.env;"
// parseInt/parseFloat
"max: parseInt(process.env.DATABASE_POOL_SIZE || '10')"
Risk Levels
- critical: Missing variable with no defaults, used in multiple places
- high: Secrets, database configs, or widely-used variables with issues
- medium: Undocumented or inconsistently used variables
- low: Minor issues like unused variables
- info: Well-configured variables with no issues
Common Issues
- MISSING: Used in code but not defined anywhere
- UNDOCUMENTED: Not in .env.example
- DEAD: Defined but never used
- INCONSISTENT_DEFAULT: Has defaults in some places but not others
- PLACEHOLDER_VALUE: Contains placeholder text
- NO_VALIDATION: No validation or error handling
Use Cases
- Debugging: Understand where a variable is used and how
- Refactoring: See all usages before renaming or removing
- Security Review: Analyze how secrets are handled
- Default Values: Check if fallbacks are appropriate
- Impact Analysis: Assess impact of changing a variable
- Documentation: Generate detailed variable documentation
