[Phase 2.5] ANTHROPIC_API_KEY not reliably propagated to CLI subprocesses

[frankbria]

Problem

When running the CLI via subprocess (e.g., from e2e tests or scripts), ANTHROPIC_API_KEY is not reliably inherited. This causes silent failures where:

1. codeframe tasks generate falls back to "simple extraction" instead of LLM generation
2. codeframe work start --execute completes in ~1.6s without doing real work (no API calls made)
3. Both return exit code 0, masking the failure

Root Cause

The environment variable must be explicitly set in the subprocess environment. The _build_env() method in GoldenPathRunner copies os.environ, but if the parent process loaded the key from .env after the environment was already established, child processes don't inherit it.

Observed Behavior

codeframe tasks generate
# Output: "LLM generation failed (ANTHROPIC_API_KEY not set...), using simple extraction"
# Exit code: 0  ← NOT an error from CLI perspective

Current Workaround

The e2e conftest.py has _ensure_api_key() that eagerly loads from .env at import time:

def _ensure_api_key():
    if os.environ.get("ANTHROPIC_API_KEY"):
        return
    env_file = CODEFRAME_ROOT / ".env"
    # ... reads .env and sets os.environ

Proposed Fix

Two complementary changes:

1. CLI should fail loudly when ANTHROPIC_API_KEY is required but missing (for commands like tasks generate, work start --execute). Instead of falling back silently, print a clear error and exit with non-zero code.

2. GoldenPathRunner._build_env() should explicitly load from .env if the key isn't in the environment, similar to how conftest.py does it.

Files

• codeframe/cli/app.py — Task generation and work execution commands
• tests/e2e/cli/golden_path_runner.py — _build_env() method
• tests/e2e/cli/conftest.py — _ensure_api_key() workaround

[traycerai]

Plan

Observations

The codebase currently loads .env files at CLI startup (lines 30-39 in file:codeframe/cli/app.py), but has two critical issues:

1. Silent fallback in task generation: file:codeframe/core/tasks.py catches all exceptions in _generate_tasks_with_llm() (line 519-522) and falls back to simple extraction, masking API key errors
2. Subprocess environment inheritance: When CLI is invoked via subprocess, environment variables loaded from .env in the parent process aren't automatically inherited by child processes
3. Exit code 0 on failure: Both tasks generate and work start --execute return success even when LLM operations fail due to missing API key

The AnthropicProvider correctly validates the API key (lines 60-65 in file:codeframe/adapters/llm/anthropic.py), and runtime.execute_agent() has validation (lines 636-640 in file:codeframe/core/runtime.py), but errors are either caught silently or occur after the command has already started.

Approach

Implement fail-fast validation at the CLI command level before attempting LLM operations. Add explicit API key validation in tasks generate and work start --execute commands to fail loudly with clear error messages and non-zero exit codes. For test infrastructure, create a helper utility that ensures .env is loaded before subprocess execution, making the environment variable available to child processes. This approach maintains backward compatibility while preventing silent failures.

Implementation Steps

1. Add API Key Validation Helper

File: file:codeframe/cli/validators.py (new file)

Create a reusable validation function that:

• Checks for ANTHROPIC_API_KEY in environment
• Attempts to load from .env if not found
• Returns clear error message if still missing
• Can be called from any CLI command that requires the API key

The function should:

def require_anthropic_api_key() -> str:
    """Ensure ANTHROPIC_API_KEY is available.
    
    Returns:
        The API key value
        
    Raises:
        typer.Exit: If API key is not available with exit code 1
    """

2. Update tasks generate Command

File: file:codeframe/cli/app.py

In the tasks_generate function (starting at line 1510):

• Add validation call at the beginning when no_llm=False
• Call require_anthropic_api_key() before calling tasks.generate_from_prd()
• Position the check after workspace loading but before LLM operations
• Only validate when LLM will actually be used (skip if --no-llm flag is set)

This ensures the command fails immediately with a clear error message rather than falling back silently.

3. Update work start --execute Command

File: file:codeframe/cli/app.py

In the work_start function (starting at line 1957):

• Add validation call when execute=True
• Call require_anthropic_api_key() before calling runtime.execute_agent()
• Position the check after task lookup but before agent execution
• Skip validation when stub=True (stub mode doesn't need API key)

This provides early validation before the expensive agent setup process.

4. Improve Error Handling in Task Generation

File: file:codeframe/core/tasks.py

In the generate_from_prd function (lines 498-538):

• Make the exception handling more specific
• Catch ValueError separately from other exceptions
• Re-raise ValueError from API key validation instead of falling back
• Only fall back to simple extraction for actual LLM API errors (rate limits, network issues, etc.)
• Update the fallback message to be more specific about why it fell back

In _generate_tasks_with_llm function (lines 541-596):

• Let ValueError from AnthropicProvider.__init__ propagate up
• Only catch API-specific exceptions (rate limits, network errors)

5. Create Test Helper for Environment Loading

File: file:tests/e2e/cli/conftest.py (new file)

Create the _ensure_api_key() helper mentioned in the issue:

def _ensure_api_key():
    """Ensure ANTHROPIC_API_KEY is loaded from .env for subprocess tests.
    
    When running CLI via subprocess, environment variables must be explicitly
    set. This helper loads from .env if the key isn't already in os.environ.
    """

This function should:

• Check if ANTHROPIC_API_KEY exists in os.environ
• If not, locate and load from .env file in project root
• Set the key in os.environ so subprocesses inherit it
• Be called at module import time or in a pytest fixture

6. Create Test Runner with Environment Propagation

File: file:tests/e2e/cli/golden_path_runner.py (new file)

Create a GoldenPathRunner class for running CLI commands in tests:

The class should have:

• _build_env() method that creates subprocess environment
• Logic to copy os.environ as base
• Explicit loading from .env if ANTHROPIC_API_KEY not in environment
• Method to run CLI commands with proper environment propagation

The _build_env() method should:

def _build_env(self) -> dict[str, str]:
    """Build environment for subprocess with .env loading."""
    env = os.environ.copy()
    
    # Ensure API key is loaded from .env if not in environment
    if "ANTHROPIC_API_KEY" not in env:
        env_file = CODEFRAME_ROOT / ".env"
        if env_file.exists():
            # Load and parse .env file
            # Set ANTHROPIC_API_KEY in env dict
    
    return env

7. Update Error Messages

File: file:codeframe/adapters/llm/anthropic.py

Enhance the error message in AnthropicProvider.__init__ (lines 61-65):

• Make it more actionable for CLI users
• Mention the specific commands that require the key
• Reference the .env.example file
• Suggest running codeframe auth setup --provider anthropic as alternative

8. Add Integration Tests

File: file:tests/e2e/cli/test_api_key_validation.py (new file)

Create tests that verify:

• codeframe tasks generate fails with exit code 1 when API key missing
• codeframe work start --execute fails with exit code 1 when API key missing
• Error messages are clear and actionable
• Commands succeed when API key is present
• --no-llm flag bypasses validation in tasks generate
• --stub flag bypasses validation in work start

9. Update Documentation

Files:

• file:README.md
• file:TESTING.md

Add notes about:

• The requirement for ANTHROPIC_API_KEY in .env for LLM operations
• How to run tests that invoke CLI via subprocess
• The difference between unit tests (mocked) and e2e tests (real API)
• How the environment variable propagation works in test scenarios

Visual Flow

sequenceDiagram
    participant User
    participant CLI as CLI Command
    participant Validator as require_anthropic_api_key()
    participant Env as Environment/.env
    participant LLM as LLM Provider
    
    User->>CLI: codeframe tasks generate
    CLI->>Validator: Check API key required
    Validator->>Env: Check ANTHROPIC_API_KEY
    
    alt API Key Missing
        Env-->>Validator: Not found
        Validator->>Env: Try load from .env
        alt .env has key
            Env-->>Validator: Key loaded
            Validator-->>CLI: OK
            CLI->>LLM: Proceed with generation
        else .env missing or no key
            Env-->>Validator: Still not found
            Validator-->>CLI: Raise typer.Exit(1)
            CLI-->>User: Error: ANTHROPIC_API_KEY not set
        end
    else API Key Present
        Env-->>Validator: Found
        Validator-->>CLI: OK
        CLI->>LLM: Proceed with generation
        LLM-->>CLI: Tasks generated
        CLI-->>User: Success (exit 0)
    end

Loading

Testing Strategy

Test Type	Location	Purpose
Unit	file:tests/cli/test_validators.py	Test require_anthropic_api_key() function in isolation
Integration	file:tests/e2e/cli/test_api_key_validation.py	Test CLI commands fail correctly when key missing
E2E	file:tests/e2e/cli/test_golden_path_runner.py	Test subprocess environment propagation

Migration Notes

• Existing behavior preserved: Commands that don't use LLM are unaffected
• --no-llm flag continues to work without API key requirement
• --stub flag continues to work without API key requirement
• Error messages are more helpful than current silent fallback
• Exit codes now correctly indicate failure (non-zero) vs success (zero)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently loads `.env` files at CLI startup (lines 30-39 in `file:codeframe/cli/app.py`), but has two critical issues:

1. **Silent fallback in task generation**: `file:codeframe/core/tasks.py` catches all exceptions in `_generate_tasks_with_llm()` (line 519-522) and falls back to simple extraction, masking API key errors
2. **Subprocess environment inheritance**: When CLI is invoked via subprocess, environment variables loaded from `.env` in the parent process aren't automatically inherited by child processes
3. **Exit code 0 on failure**: Both `tasks generate` and `work start --execute` return success even when LLM operations fail due to missing API key

The `AnthropicProvider` correctly validates the API key (lines 60-65 in `file:codeframe/adapters/llm/anthropic.py`), and `runtime.execute_agent()` has validation (lines 636-640 in `file:codeframe/core/runtime.py`), but errors are either caught silently or occur after the command has already started.

## Approach

Implement fail-fast validation at the CLI command level before attempting LLM operations. Add explicit API key validation in `tasks generate` and `work start --execute` commands to fail loudly with clear error messages and non-zero exit codes. For test infrastructure, create a helper utility that ensures `.env` is loaded before subprocess execution, making the environment variable available to child processes. This approach maintains backward compatibility while preventing silent failures.

## Implementation Steps

### 1. Add API Key Validation Helper

**File**: `file:codeframe/cli/validators.py` (new file)

Create a reusable validation function that:
- Checks for `ANTHROPIC_API_KEY` in environment
- Attempts to load from `.env` if not found
- Returns clear error message if still missing
- Can be called from any CLI command that requires the API key

The function should:
```python
def require_anthropic_api_key() -> str:
    """Ensure ANTHROPIC_API_KEY is available.
    
    Returns:
        The API key value
        
    Raises:
        typer.Exit: If API key is not available with exit code 1
    """
```

### 2. Update `tasks generate` Command

**File**: `file:codeframe/cli/app.py`

In the `tasks_generate` function (starting at line 1510):

- Add validation call at the beginning when `no_llm=False`
- Call `require_anthropic_api_key()` before calling `tasks.generate_from_prd()`
- Position the check after workspace loading but before LLM operations
- Only validate when LLM will actually be used (skip if `--no-llm` flag is set)

This ensures the command fails immediately with a clear error message rather than falling back silently.

### 3. Update `work start --execute` Command

**File**: `file:codeframe/cli/app.py`

In the `work_start` function (starting at line 1957):

- Add validation call when `execute=True`
- Call `require_anthropic_api_key()` before calling `runtime.execute_agent()`
- Position the check after task lookup but before agent execution
- Skip validation when `stub=True` (stub mode doesn't need API key)

This provides early validation before the expensive agent setup process.

### 4. Improve Error Handling in Task Generation

**File**: `file:codeframe/core/tasks.py`

In the `generate_from_prd` function (lines 498-538):

- Make the exception handling more specific
- Catch `ValueError` separately from other exceptions
- Re-raise `ValueError` from API key validation instead of falling back
- Only fall back to simple extraction for actual LLM API errors (rate limits, network issues, etc.)
- Update the fallback message to be more specific about why it fell back

In `_generate_tasks_with_llm` function (lines 541-596):
- Let `ValueError` from `AnthropicProvider.__init__` propagate up
- Only catch API-specific exceptions (rate limits, network errors)

### 5. Create Test Helper for Environment Loading

**File**: `file:tests/e2e/cli/conftest.py` (new file)

Create the `_ensure_api_key()` helper mentioned in the issue:

```python
def _ensure_api_key():
    """Ensure ANTHROPIC_API_KEY is loaded from .env for subprocess tests.
    
    When running CLI via subprocess, environment variables must be explicitly
    set. This helper loads from .env if the key isn't already in os.environ.
    """
```

This function should:
- Check if `ANTHROPIC_API_KEY` exists in `os.environ`
- If not, locate and load from `.env` file in project root
- Set the key in `os.environ` so subprocesses inherit it
- Be called at module import time or in a pytest fixture

### 6. Create Test Runner with Environment Propagation

**File**: `file:tests/e2e/cli/golden_path_runner.py` (new file)

Create a `GoldenPathRunner` class for running CLI commands in tests:

The class should have:
- `_build_env()` method that creates subprocess environment
- Logic to copy `os.environ` as base
- Explicit loading from `.env` if `ANTHROPIC_API_KEY` not in environment
- Method to run CLI commands with proper environment propagation

The `_build_env()` method should:
```python
def _build_env(self) -> dict[str, str]:
    """Build environment for subprocess with .env loading."""
    env = os.environ.copy()
    
    # Ensure API key is loaded from .env if not in environment
    if "ANTHROPIC_API_KEY" not in env:
        env_file = CODEFRAME_ROOT / ".env"
        if env_file.exists():
            # Load and parse .env file
            # Set ANTHROPIC_API_KEY in env dict
    
    return env
```

### 7. Update Error Messages

**File**: `file:codeframe/adapters/llm/anthropic.py`

Enhance the error message in `AnthropicProvider.__init__` (lines 61-65):

- Make it more actionable for CLI users
- Mention the specific commands that require the key
- Reference the `.env.example` file
- Suggest running `codeframe auth setup --provider anthropic` as alternative

### 8. Add Integration Tests

**File**: `file:tests/e2e/cli/test_api_key_validation.py` (new file)

Create tests that verify:
- `codeframe tasks generate` fails with exit code 1 when API key missing
- `codeframe work start --execute` fails with exit code 1 when API key missing
- Error messages are clear and actionable
- Commands succeed when API key is present
- `--no-llm` flag bypasses validation in tasks generate
- `--stub` flag bypasses validation in work start

### 9. Update Documentation

**Files**: 
- `file:README.md`
- `file:TESTING.md`

Add notes about:
- The requirement for `ANTHROPIC_API_KEY` in `.env` for LLM operations
- How to run tests that invoke CLI via subprocess
- The difference between unit tests (mocked) and e2e tests (real API)
- How the environment variable propagation works in test scenarios

## Visual Flow

```mermaid
sequenceDiagram
    participant User
    participant CLI as CLI Command
    participant Validator as require_anthropic_api_key()
    participant Env as Environment/.env
    participant LLM as LLM Provider
    
    User->>CLI: codeframe tasks generate
    CLI->>Validator: Check API key required
    Validator->>Env: Check ANTHROPIC_API_KEY
    
    alt API Key Missing
        Env-->>Validator: Not found
        Validator->>Env: Try load from .env
        alt .env has key
            Env-->>Validator: Key loaded
            Validator-->>CLI: OK
            CLI->>LLM: Proceed with generation
        else .env missing or no key
            Env-->>Validator: Still not found
            Validator-->>CLI: Raise typer.Exit(1)
            CLI-->>User: Error: ANTHROPIC_API_KEY not set
        end
    else API Key Present
        Env-->>Validator: Found
        Validator-->>CLI: OK
        CLI->>LLM: Proceed with generation
        LLM-->>CLI: Tasks generated
        CLI-->>User: Success (exit 0)
    end
```

## Testing Strategy

| Test Type | Location | Purpose |
|-----------|----------|---------|
| Unit | `file:tests/cli/test_validators.py` | Test `require_anthropic_api_key()` function in isolation |
| Integration | `file:tests/e2e/cli/test_api_key_validation.py` | Test CLI commands fail correctly when key missing |
| E2E | `file:tests/e2e/cli/test_golden_path_runner.py` | Test subprocess environment propagation |

## Migration Notes

- Existing behavior preserved: Commands that don't use LLM are unaffected
- `--no-llm` flag continues to work without API key requirement
- `--stub` flag continues to work without API key requirement
- Error messages are more helpful than current silent fallback
- Exit codes now correctly indicate failure (non-zero) vs success (zero)

---

Execution Information

Branch: main
Commit: e04112c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#304 - test(cli): add comprehensive v2 CLI integration test suite [merged]
#317 - feat(cli): add interactive PRD generation via Socratic discovery [merged]
#320 - test(core): add integration tests for credentials and environment modules [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!