prodigy 0.4.4

## Environment Configuration

Environment variables can be configured at multiple levels in Prodigy workflows, providing flexible control over workflow execution across different environments and contexts.

**Source**: Configuration structures defined in `src/cook/environment/config.rs:11-144`, workflow configuration in `src/config/workflow.rs:12-39`.

### Overview

Prodigy supports comprehensive environment configuration including:
- Global environment variables with static, dynamic, and conditional values
- Secret management with automatic log masking
- Environment profiles for different deployment contexts
- Environment files (.env format)
- Step-level environment overrides
- Variable interpolation in commands

This subsection provides a quick introduction to environment configuration. For comprehensive coverage, see the [Environment chapter](../environment/index.md).

### Global Environment Variables

Define environment variables in the `env:` block at the workflow root. Variables can be static strings, dynamically computed from commands, or conditionally set based on expressions.

**Source**: `workflows/environment-example.yml:4-18`

```yaml
env:
  # Static environment variables
  NODE_ENV: production
  API_URL: https://api.example.com

  # Dynamic environment variable (computed from command)
  WORKERS:
    command: "nproc 2>/dev/null || echo 4"
    cache: true

  # Conditional environment variable
  DEPLOY_ENV:
    condition: "${branch} == 'main'"
    when_true: "production"
    when_false: "staging"
```

**Type Definitions** (`src/cook/environment/config.rs:38-81`):
- `EnvValue::Static(String)` - Static string value
- `EnvValue::Dynamic(DynamicEnv)` - Computed from command with optional caching
- `EnvValue::Conditional(ConditionalEnv)` - Based on condition expression

### Environment Files

Load environment variables from .env format files using the `env_files:` field.

**Source**: `workflows/environment-example.yml:25-27`, `src/cook/environment/config.rs:22-23`

```yaml
env_files:
  - .env.production
  - .env.local
```

Variables from env files are merged with global env variables, with explicit env: block taking precedence.

For detailed information about .env file format and loading behavior, see [Environment Files](../environment/environment-files.md).

### Secrets Management

Secret environment variables are automatically masked in all log output, preventing accidental credential leaks.

**Source**: `workflows/mapreduce-env-example.yml:23-26`, `src/cook/environment/config.rs:86-112`

```yaml
secrets:
  # Simple secret reference
  API_KEY: "${env:SECRET_API_KEY}"

  # Provider-based secret
  API_TOKEN:
    provider: env
    key: "GITHUB_TOKEN"
```

**Secret Providers** (`src/cook/environment/config.rs:101-112`):
- `env` - Environment variable
- `file` - File-based secret
- `vault` - HashiCorp Vault
- `aws` - AWS Secrets Manager
- Custom providers

For comprehensive secrets management documentation, see [Secrets Management](../environment/secrets-management.md).

### Environment Profiles

Profiles enable different environment configurations for various deployment contexts (development, staging, production).

**Source**: `workflows/environment-example.yml:30-39`, `src/cook/environment/config.rs:116-124`

```yaml
profiles:
  development:
    description: "Development environment with debug enabled"
    NODE_ENV: development
    API_URL: http://localhost:3000
    DEBUG: "true"

  production:
    description: "Production environment"
    NODE_ENV: production
    API_URL: https://api.example.com
    DEBUG: "false"
```

**Activate a profile**:
```bash
# Via command line flag
prodigy run workflow.yml --profile development

# Via environment variable
export PRODIGY_PROFILE=production
prodigy run workflow.yml
```

For detailed profile configuration and best practices, see [Environment Profiles](../environment/environment-profiles.md).

### Step-Level Environment Overrides

Commands can define their own environment variables that override global and profile settings.

**Source**: `workflows/environment-example.yml:47-60`, `src/cook/environment/config.rs:126-144`

```yaml
commands:
  - name: "Build frontend"
    shell: "echo 'Building with NODE_ENV='$NODE_ENV"
    env:
      BUILD_TARGET: production
      OPTIMIZE: "true"
    working_dir: ./frontend

  - name: "Run tests"
    shell: "pytest"
    env:
      PYTHONPATH: "./src:./tests"
      TEST_ENV: "true"
    working_dir: ./backend
    temporary: true  # Environment restored after this step
```

**Step Environment Fields** (`src/cook/environment/config.rs:128-144`):
- `env: HashMap<String, String>` - Step-specific variables
- `working_dir: Option<PathBuf>` - Working directory for this step
- `clear_env: bool` - Clear parent environment before applying step env
- `temporary: bool` - Restore environment after step completes

For detailed step-level configuration, see [Per-Command Environment Overrides](../environment/per-command-environment-overrides.md).

### Variable Interpolation

Environment variables can be referenced in commands using two syntaxes: `$VAR` or `${VAR}`.

**Source**: `workflows/mapreduce-env-example.yml:44-80`

```yaml
env:
  PROJECT_NAME: "my-project"
  OUTPUT_DIR: "output"

commands:
  # Both syntaxes work
  - shell: "echo Starting $PROJECT_NAME"
  - shell: "echo Output directory: ${OUTPUT_DIR}"

  # Use ${} for complex expressions
  - shell: "cp summary.json ${OUTPUT_DIR}/${PROJECT_NAME}-report.json"
```

Variable interpolation is available in:
- Shell commands
- Claude commands
- File paths
- MapReduce configuration (max_parallel, timeout, etc.)

For comprehensive variable interpolation documentation, see [Variable Interpolation](../variables/available-variables.md).

### Environment Precedence

When the same variable is defined at multiple levels, precedence is:

1. **Step-level env** (highest priority)
2. **Profile env**
3. **Global env**
4. **System environment** (lowest priority)

**Source**: Precedence logic in `src/cook/environment/builder.rs:48-53`, tests in `tests/environment_workflow_test.rs:62-132`

For detailed precedence rules and examples, see [Environment Precedence](../environment/environment-precedence.md).

### MapReduce Environment Variables

Environment variables are available across all MapReduce workflow phases: setup, map, reduce, and merge.

**Source**: `workflows/mapreduce-env-example.yml:1-95`, `src/config/mapreduce.rs:24-38`

```yaml
name: mapreduce-workflow
mode: mapreduce

env:
  PROJECT_NAME: "my-project"
  MAX_RETRIES: "3"

setup:
  - shell: "echo Starting $PROJECT_NAME"

map:
  agent_template:
    - claude: "/process --project $PROJECT_NAME --retries $MAX_RETRIES"

reduce:
  - shell: "echo Completed $PROJECT_NAME workflow"

merge:
  commands:
    - shell: "echo Merging $PROJECT_NAME changes"
```

For comprehensive MapReduce environment documentation, see [MapReduce Environment Variables](../environment/mapreduce-environment-variables.md).

### Complete Example

This example demonstrates multiple environment features working together.

**Source**: Complete workflow in `workflows/environment-example.yml:1-70`

```yaml
# Global environment with static, dynamic, and conditional values
env:
  NODE_ENV: production
  API_URL: https://api.example.com

  WORKERS:
    command: "nproc 2>/dev/null || echo 4"
    cache: true

  DEPLOY_ENV:
    condition: "${branch} == 'main'"
    when_true: "production"
    when_false: "staging"

# Secrets (masked in logs)
secrets:
  API_KEY: "${env:SECRET_API_KEY}"

# Environment files
env_files:
  - .env.production

# Profiles
profiles:
  development:
    NODE_ENV: development
    API_URL: http://localhost:3000
    DEBUG: "true"

# Commands with step-level overrides
commands:
  - name: "Build"
    shell: "npm run build"
    env:
      BUILD_TARGET: production
    working_dir: ./frontend

  - name: "Deploy"
    shell: "echo Deploying to $DEPLOY_ENV"
```