AGEN-4 - trckr

← AGEN-4

feature

Created: 2026-02-03 • Updated: 2026-02-03

Relationships Loading...

# .env File Support

Implement --env-file CLI flag to load environment variables from .env files.

## Scope
~120 lines of code + tests

## Implementation
1. Add --env-file CLI argument (supports multiple files) (cli.py)
2. Load .env file using simple parser (KEY=value format)
3. Merge loaded env with workflow environment (precedence)
4. Support multiple --env-file flags (later files override earlier)
5. Validate file exists before loading (clear error if missing)
6. Handle comments (#), blank lines, quotes

## YAML API
\`\`\`bash
agent-yaml run workflow.yaml --env-file .env.production
agent-yaml run workflow.yaml --env-file .env --env-file .env.local
\`\`\`

## Precedence
System env < .env file < workflow environment < task env < CLI --var

## .env File Format
\`\`\`bash
# Production environment
DATABASE_URL=postgres://localhost/prod
API_KEY=secret123
LOG_LEVEL=info

# Quotes supported
MESSAGE="Hello World"
\`\`\`

## Files to Modify
- src/cli.py (~80 lines)
- tests/test_env_file.py (new, ~40 lines)

## Tests Required
- Load .env file successfully
- Variables from .env available to tasks
- Multiple .env files (later overrides earlier)
- Missing .env file raises error with clear message
- Empty .env file works (no crash)
- Comments and blank lines handled correctly
- Quoted values parsed correctly

## QA Validation Steps

### 1. Basic .env Loading
**Action:**
Create .env file:
\`\`\`
MY_KEY=my_value
DB_URL=postgres://localhost
\`\`\`
Run: \`agent-yaml run workflow.yaml --env-file .env\`

**Expected:** Variables loaded and available
**Verify:** Task can access MY_KEY and DB_URL

### 2. Multiple .env Files
**Action:**
Create .env: \`KEY=base\`
Create .env.override: \`KEY=override\`
Run: \`agent-yaml run workflow.yaml --env-file .env --env-file .env.override\`

**Expected:** KEY=override (later file wins)
**Verify:** Task sees override value

### 3. Precedence Test
**Action:**
.env file: \`VAR=from_file\`
Workflow YAML: \`environment: {VAR: "from_yaml"}\`
Run with --env-file .env

**Expected:** VAR=from_yaml (workflow overrides .env)
**Verify:** Correct precedence

### 4. Missing File Test
**Action:** Run with --env-file nonexistent.env
**Expected:** Clear error: "Environment file not found: nonexistent.env"
**Verify:** Workflow stops with helpful error

### Pass Criteria
✅ All 4 tests pass
✅ Precedence order correct
✅ Unit tests pass

### Fail Criteria
❌ Any test fails
❌ File not found error unclear
❌ Quoted values not parsed correctly

Pull Requests (comma-separated URLs)

Attachments

Comments (3)

QA-Agent · 2026-02-03

## QA Verification Complete **Status:** ✅ PASSED - Ready for production All acceptance criteria verified: - ✅ Basic .env loading works - ✅ Multiple .env files merge correctly (later overrides earlier) - ✅ Precedence order enforced (system < .env < workflow < task < --var) - ✅ Missing file error is clear and helpful - ✅ All 762 tests pass (29 new + 733 existing) - ✅ Edge cases handled (quotes, empty values, comments, blank lines) Implementation is complete, correct, and production-ready. Full QA report: /tmp/qa-AGEN-4.md

agent · 2026-02-03

## Implementation Complete ### Changes Made - **src/cli.py:33-146** - Added `EnvFileError` exception class, `parse_env_file()` function, and `load_env_files()` function - **src/cli.py:776-781** - Added `--env-file` CLI argument (supports multiple files via `action="append"`) - **src/cli.py:338-362** - Integrated env file loading into `run_workflow()` after schema validation but before execution - **tests/test_env_file.py** - New test file with 29 unit tests covering all requirements - **tests/test_cli.py** - Updated existing tests to include new `env_files` parameter ### Features Implemented 1. Load environment variables from .env files using `--env-file` flag 2. Support for multiple .env files (later files override earlier) 3. Standard .env format support: - KEY=value (basic assignment) - Quoted values (single and double quotes strip outer quotes) - Comments (#) and blank lines ignored - Values with equals signs preserved 4. Clear error message for missing files: "Environment file not found: <path>" 5. Correct precedence: system env < .env file < workflow environment < task env < CLI --var ### Test Results All 762 tests pass (29 new tests + 733 existing tests): - `TestParseEnvFile`: 17 tests for .env parsing edge cases - `TestLoadEnvFiles`: 5 tests for multi-file merging - `TestEnvFilePrecedence`: 2 tests for correct override behavior - `TestEnvFileWithWorkflow`: 5 tests for integration with run_workflow ### Verification Steps 1. Basic .env loading: ✅ Variables loaded and available 2. Multiple .env files: ✅ Later file overrides earlier 3. Precedence test: ✅ Workflow env overrides .env file 4. Missing file test: ✅ Clear error message shown

triage-agent · 2026-02-03

## Feature Triage Complete **Status:** NOT IMPLEMENTED - Ready for development **Summary:** This feature adds `--env-file` CLI flag to load environment variables from `.env` files. The feature is well-scoped and doesn't conflict with existing code. **Implementation Location:** - `src/cli.py` - Add argument parsing and `parse_env_file()` function (~80 lines) - `tests/test_env_file.py` - New test file (~40 lines) **Complexity:** Low - Simple string parsing, no new dependencies **Key Design Decisions:** - Precedence: System env < .env file(s) < workflow environment < task env < CLI --var - No external dependencies (simple ~30 line parser) - Multiple `--env-file` flags supported (later overrides earlier) See triage report at: `/tmp/triage-AGEN-4.md`