Detect Env Vars

Detect Environment Variables

Overview

The detect-env-vars skill scans a project directory and builds a complete, structured inventory of every environment variable in use. It reads from three independent source types and merges the results:

Quick Start

from harness_skills.env_var_detector import detect_env_vars

result = detect_env_vars(".")          # scan current directory
print(result.unique_var_names)         # sorted, de-duplicated names
print(result.total_vars_found)         # total occurrences (not unique)
print(result.dotenv_files_found)       # .env.example paths scanned
print(result.source_files_scanned)     # number of source files inspected

# Granular scanning
from harness_skills.env_var_detector import (
    scan_dotenv_file,
    scan_config_file,
    scan_source_file,
)
from pathlib import Path

root = Path(".")

# Parse a single .env.example
entries = scan_dotenv_file(Path(".env.example"), root)
for e in entries:
    status = "required" if e.required else "optional"
    print(f"  [{status}] {e.name}={e.default_value}  # {e.comment}")

# Extract ${VAR} refs from a YAML config
entries = scan_config_file(Path("config/app.yaml"), root)

# Scan a Python file for os.environ references
entries = scan_source_file(Path("app/settings.py"), root, "python")

Function Reference

detect_env_vars(path, *, skip_dirs, include_config, include_source)

Recursively scans path and returns an EnvVarDetectionResult.

scan_dotenv_file(path, root)

Parses a single .env.example-style file.

• KEY=value lines → required=True
• # KEY=value lines → required=False (documented optional variable)
• Preceding comment lines are attached to the next variable as comment

scan_config_file(path, root)

Scans any text-based config file for ${VAR_NAME} and $VAR_NAME patterns.

scan_source_file(path, root, language)

Scans a single source file. Supported language values: "python", "javascript", "typescript", "go", "ruby", "shell".

Data Models

EnvVarEntry

class EnvVarEntry(BaseModel):
    name: str               # e.g. DATABASE_URL
    source: EnvVarSource    # dotenv_example | config_file | source_code
    file_path: str          # repo-relative path
    line_number: int | None
    default_value: str | None
    comment: str | None
    required: bool          # False = commented-out optional variable

EnvVarDetectionResult

class EnvVarDetectionResult(HarnessResponse):
    command: str                     # "detect-env-vars"
    status: Status                   # always "passed"
    scanned_path: str
    env_vars: list[EnvVarEntry]      # one per occurrence
    unique_var_names: list[str]      # sorted, de-duplicated names
    dotenv_files_found: list[str]
    config_files_found: list[str]
    source_files_scanned: int
    total_vars_found: int

Detection Patterns

Python

JavaScript / TypeScript

Go

Ruby

Config files

Key Files

Notes

• The skill is read-only — it never modifies project files.
• Variables found in multiple files produce one EnvVarEntry each (the env_vars list may contain duplicates across files); unique_var_names is always de-duplicated.
• The built-in skip list prevents scanning .git, .venv, node_modules, __pycache__, dist, build, .claw-forge, and .tox.
• Related skills: /detect-api-style, /module-boundaries, /harness:context.