# How DCG_BYPASS and DCGFAILCLOSED Override DCG Config Settings

> Learn how DCG_BYPASS and DCGFAILCLOSED environment variables override destructive_command_guard TOML settings. Understand their impact on command execution and error handling.

- Repository: [Jeff Emanuel/destructive_command_guard](https://github.com/Dicklesworthstone/destructive_command_guard)
- Tags: how-to-guide
- Published: 2026-07-13

---

**Environment variables take precedence over TOML configuration files in the destructive_command_guard, with `DCG_BYPASS=1` silently allowing all commands and `DCGFAILCLOSED=1` forcing hard failures on configuration errors.**

The `dcg` (destructive command guard) utility implements a layered configuration system that allows temporary runtime overrides without modifying disk-based settings. According to the source code in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs), environment variables prefixed with `DCG` automatically override values from project-level, user-level, and system-level TOML files.

## Configuration Layering and Priority

The guard loads settings from five distinct sources, with each higher layer superseding the one below it. As documented in the header comments of [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs) (lines 4–5), the priority order is:

1. **Environment variables** – highest priority
2. Project-level TOML ([`.dcg.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg.toml))
3. User-level TOML (`~/.config/dcg/config.toml`)
4. System-level TOML ([`/etc/dcg/config.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main//etc/dcg/config.toml))
5. Compiled defaults – lowest priority

The constant `ENV_PREFIX` is defined as `"DCG"` in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs). The `Config::from_env` implementation scans all process environment variables beginning with this prefix and maps them to corresponding configuration fields, overriding any values loaded from TOML files.

## How DCG_BYPASS Overrides Policy Settings

### Implementation in src/config.rs

When `DCG_BYPASS=1` (or any non-empty value) is present in the environment, the configuration system sets the `policy.bypass` flag to `true`. This occurs during the initialization phase when `from_env` processes the variable and applies it to the configuration struct.

### Short-Circuit Behavior in src/main.rs

The evaluation pipeline checks `policy.bypass` early in execution. When enabled, the guard immediately exits with status 0 without performing pattern matching or emitting denial JSON. This short-circuit behavior completely disables the protective guard for that invocation:

- No regex patterns are evaluated against the command
- No JSON output is produced to stdout
- The command is silently allowed regardless of its destructive potential

The end-to-end tests in [`tests/e2e_real_service.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/tests/e2e_real_service.rs) (lines 725–745) verify this behavior by asserting that processes exit cleanly with no output when the variable is set.

```bash

# Bypass all destructive command checks

DCG_BYPASS=1 dcg "rm -rf /important/data"

# Exit status: 0

# Output: none (silent allow)

```

## How DCGFAILCLOSED Overrides Failure Mode

### Mapping to policy.fail_closed

`DCGFAILCLOSED` maps to the configuration key `policy.fail_closed`. Unlike the standard behavior that warns and continues when encountering malformed configuration files, enabling this flag treats configuration loading errors as fatal.

### Hard Failure vs. Warning Behavior

When `DCGFAILCLOSED` is set, any failure to load a mandatory configuration layer—such as a syntax error in `~/.config/dcg/config.toml`—results in immediate termination:

- The guard outputs a JSON error object with a code in the `DCG-2xxx` range
- The command is **denied** regardless of content because the guard remains "closed"
- This prevents execution when the security policy cannot be reliably determined

```bash

# Force hard failure on config errors

# (assuming malformed ~/.config/dcg/config.toml exists)

DCGFAILCLOSED=1 dcg "git status"

# Outputs: {"error": "DCG-2002", "message": "Configuration parse error"}

# Command denied

```

## Practical Override Examples

These environment variables allow emergency overrides without editing configuration files. Common scenarios include:

```bash

# Temporary bypass during maintenance scripts

export DCG_BYPASS=1
./dangerous_cleanup.sh
unset DCG_BYPASS

# CI/CD pipeline requiring strict failure mode

DCGFAILCLOSED=1 DCG_BYPASS=0 dcg "sudo rm -rf /tmp/build"

```

Note that `DCG_BYPASS` takes precedence over `DCGFAILCLOSED` when both are set, as the bypass check occurs earlier in the pipeline.

## Summary

- **Environment variables have highest priority** in the layered configuration system defined in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs)
- **`DCG_BYPASS=1`** sets `policy.bypass=true`, causing immediate silent exit with status 0 and no pattern evaluation
- **`DCGFAILCLOSED`** sets `policy.fail_closed=true`, converting configuration warnings into hard JSON errors with codes in the `DCG-2xxx` range
- Both variables are processed by `Config::from_env` and override any TOML-based settings from project, user, or system levels
- The bypass behavior is tested in [`tests/e2e_real_service.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/tests/e2e_real_service.rs) while fail-closed logic is exercised in configuration validation tests

## Frequently Asked Questions

### What is the exact priority order for DCG configuration sources?

The guard loads settings in the following order, with each layer overriding the previous: compiled defaults, system-level TOML ([`/etc/dcg/config.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main//etc/dcg/config.toml)), user-level TOML (`~/.config/dcg/config.toml`), project-level TOML ([`.dcg.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg.toml)), and finally environment variables with the `DCG` prefix. This hierarchy is explicitly documented in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs).

### Does DCG_BYPASS require a specific value to work?

Any non-empty value enables the bypass. While `DCG_BYPASS=1` is the conventional setting, the code checks only for the presence and non-emptiness of the variable when setting `policy.bypass` to `true`.

### How does DCGFAILCLOSED affect the output format?

When enabled and a configuration error occurs, `dcg` outputs a structured JSON object containing an error code in the `DCG-2xxx` series instead of the standard command evaluation JSON. This follows the hook protocol while indicating that the guard failed in a closed state.

### Can these environment variables be used together?

Yes, though `DCG_BYPASS` effectively neutralizes `DCGFAILCLOSED` when both are set because the bypass check occurs earlier in the execution pipeline. The guard exits silently before reaching the configuration validation logic that would trigger the fail-closed behavior.