# Dive Configuration Options: Complete Guide to CLI Flags, Environment Variables, and YAML Settings

> Explore Dive configuration options via CLI flags, environment variables, and YAML files. Customize your image analysis, CI, export, and UI settings for efficient container image inspection.

- Repository: [Alex Goodman/dive](https://github.com/wagoodman/dive)
- Tags: api-reference
- Published: 2026-03-07

---

**Dive supports extensive configuration through command-line flags, environment variables, and YAML configuration files, with all options organized into Analysis, CI, Export, and UI groups within the `cmd/dive/cli/internal/options` package.**

The `wagoodman/dive` repository provides a powerful terminal interface for analyzing Docker image layers and optimizing container efficiency. Mastering the available Dive configuration options enables you to automate CI pipelines, customize the interactive TUI, and control how container images are fetched and parsed.

## Configuration Architecture Overview

All Dive configuration options are assembled into a single top-level `Application` struct defined in [`cmd/dive/cli/internal/options/application.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/application.go). This struct embeds four specialized configuration groups that drive every aspect of the program's behavior:

- **Analysis** (`options.Analysis`): Controls image retrieval and parsing
- **CI** (`options.CI`): Configures continuous-integration mode and validation rules  
- **Export** (`options.Export`): Handles JSON report generation for non-interactive usage
- **UI** (`options.UI`): Manages terminal UI preferences including keybindings and view layouts

These groups are mapped to CLI flags via the **clio** framework and can be overridden through environment variables or a `~/.dive.yaml` configuration file.

## Analysis Configuration Options

The Analysis group, defined in [`cmd/dive/cli/internal/options/analysis.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/analysis.go), determines how Dive retrieves and processes container images.

| Flag | YAML Key | Type | Description |
|------|----------|------|-------------|
| `--source`, `-s` | `container-engine` | `string` | Container engine for fetching images (`docker` or `podman`). Default: **docker**. |
| `--ignore-errors`, `-i` | `ignore-errors` | `bool` | Continue analysis even if the image archive contains parsing errors. |
| (positional) | `image` | `string` | Image reference (e.g., `nginx:latest`). |

When using the YAML configuration, specify the engine and error handling behavior under the `analysis` key:

```yaml
analysis:
  container-engine: podman
  ignore-errors: true

```

## CI Configuration Options  

Continuous integration settings are managed in [`cmd/dive/cli/internal/options/ci.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ci.go). These options enable automated efficiency validation without launching the interactive UI.

| Flag | YAML Key | Type | Description |
|------|----------|------|-------------|
| `--ci` | `ci` | `bool` | Enable CI mode (skips the TUI). |
| `--ci-config` | `ci-config` | `string` | Path to CI rules file. Default: **.dive-ci**. |

The `rules` field in YAML accepts an `options.CIRules` struct defining thresholds:

- `lowest-efficiency`: Minimum efficiency ratio (e.g., `"0.3"`)
- `highest-wasted-bytes`: Maximum wasted space (e.g., `"10MiB"`)  
- `highest-user-wasted-percent`: Maximum wasted percentage (e.g., `"5.0"`)

Setting the environment variable `CI=true` also activates CI mode automatically.

## Export Configuration Options

JSON export functionality is controlled through [`cmd/dive/cli/internal/options/export.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/export.go), allowing headless analysis output.

| Flag | YAML Key | Type | Description |
|------|----------|------|-------------|
| `--json`, `-j` | `json-path` | `string` | Write layer analysis statistics to the specified file and exit without launching the TUI. |

This option is essential for integrating Dive into automated reporting pipelines.

## UI Configuration Options

The UI group in [`cmd/dive/cli/internal/options/ui.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui.go) aggregates four sub-components that customize the terminal interface behavior.

### Keybindings

Defined in [`cmd/dive/cli/internal/options/ui_keybindings.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui_keybindings.go), each field accepts a comma-separated list of key chords (e.g., `"up,k"`). Available bindings include:

- `Quit`, `ToggleView`, `FilterFiles`
- `Up`, `Down`, `PageUp`, `PageDown`  
- `ExtractFile`

### Diff View

Located in [`cmd/dive/cli/internal/options/ui_diff.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui_diff.go):

- `hide`: Array of change types to suppress (`added`, `removed`, `modified`, `unmodified`)

### File Tree

Configured in [`cmd/dive/cli/internal/options/ui_filetree.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui_filetree.go):

- `collapse-dir`: Collapse directories by default (`bool`)
- `pane-width`: Width of the file-tree pane as a float between 0 and 1 (`float64`)
- `show-attributes`: Display file attributes like size and mode (`bool`)

### Layer View

Defined in [`cmd/dive/cli/internal/options/ui_layers.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui_layers.go):

- `show-aggregated-changes`: Display cumulative changes across all previous layers (`bool`)

UI defaults are sourced from [`cmd/dive/cli/internal/ui/v1/config.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/ui/v1/config.go) and converted via the `Application.V1Preferences()` method:

```go
func (c Application) V1Preferences() v1.Preferences {
    return v1.Preferences{
        KeyBindings:                c.UI.Keybinding.Config,
        ShowFiletreeAttributes:     c.UI.Filetree.ShowAttributes,
        ShowAggregatedLayerChanges: c.UI.Layer.ShowAggregatedChanges,
        CollapseFiletreeDirectory:  c.UI.Filetree.CollapseDir,
        FiletreePaneWidth:          c.UI.Filetree.PaneWidth,
        FiletreeDiffHide:           nil,
    }
}

```

## Practical Configuration Examples

### Command-Line Flags

Analyze an image with Podman, ignore parsing errors, and export JSON:

```bash
dive \
  --source podman \
  --ignore-errors \
  --json report.json \
  nginx:latest

```

### CI Mode with Custom Rules

Enable CI validation using environment variables and a custom rules file:

```bash
export CI=true
dive --ci-config ./my-ci-rules.yaml alpine:3.18

```

Example [`my-ci-rules.yaml`](https://github.com/wagoodman/dive/blob/main/my-ci-rules.yaml):

```yaml
rules:
  lowest-efficiency: "0.3"
  highest-wasted-bytes: "10MiB"
  highest-user-wasted-percent: "5.0"

```

### Comprehensive YAML Configuration

Create `~/.dive.yaml` to persist preferences:

```yaml
analysis:
  container-engine: docker
  ignore-errors: true

ui:
  filetree:
    collapse-dir: true
    pane-width: 0.35
    show-attributes: false
  layer:
    show-aggregated-changes: true
  diff:
    hide: ["unmodified"]
  keybinding:
    quit: "ctrl+x"
    up: "k"
    down: "j"
    toggle-view: "tab"

```

Dive automatically reads `~/.dive.yaml` when present, or specify an alternate path with `--config`.

## Programmatic Configuration

When embedding Dive as a library, construct the `Application` struct directly:

```go
import (
    "github.com/wagoodman/dive/cmd/dive/cli/internal/options"
    "github.com/wagoodman/dive/cmd/dive/cli/internal/ui/v1"
)

func run() {
    cfg := options.Application{
        Analysis: options.Analysis{
            Image:           "busybox:latest",
            ContainerEngine: "docker",
        },
        UI: options.UI{
            Filetree: options.UIFiletree{
                CollapseDir:    false,
                PaneWidth:      0.4,
                ShowAttributes: true,
            },
        },
    }
    
    // Convert to UI preferences for the TUI
    prefs := cfg.V1Preferences()
    // Inject prefs into v1.Config for headless runs or exports
}

```

## Summary

- Dive organizes configuration into four distinct groups: **Analysis**, **CI**, **Export**, and **UI**, all embedded in the `Application` struct.
- Configuration sources follow a hierarchy: command-line flags override environment variables, which override YAML file settings.
- Analysis options in [`cmd/dive/cli/internal/options/analysis.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/analysis.go) control container engines (Docker/Podman) and error tolerance.
- CI mode settings in [`cmd/dive/cli/internal/options/ci.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ci.go) support automated efficiency validation through thresholds and rule files.
- UI customization spans keybindings, diff filters, file-tree layout, and layer aggregation, defined across [`ui_keybindings.go`](https://github.com/wagoodman/dive/blob/main/ui_keybindings.go), [`ui_diff.go`](https://github.com/wagoodman/dive/blob/main/ui_diff.go), [`ui_filetree.go`](https://github.com/wagoodman/dive/blob/main/ui_filetree.go), and [`ui_layers.go`](https://github.com/wagoodman/dive/blob/main/ui_layers.go).
- The `V1Preferences()` method in [`application.go`](https://github.com/wagoodman/dive/blob/main/application.go) translates configuration structs into runtime UI preferences.

## Frequently Asked Questions

### How do I configure Dive to use Podman instead of Docker?

Set the `--source` flag to `podman` when running the command, or specify `container-engine: podman` under the `analysis` section in your `~/.dive.yaml` file. This configuration is defined in [`cmd/dive/cli/internal/options/analysis.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/analysis.go) and accepts either `docker` (default) or `podman` as valid values.

### What is the difference between the `--ci` flag and the `CI` environment variable?

Both activate continuous integration mode, which skips the interactive TUI and performs efficiency validation. The `--ci` flag is explicit on the command line, while setting `CI=true` as an environment variable achieves the same result automatically. Both trigger the logic in [`cmd/dive/cli/internal/options/ci.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ci.go) that loads rules from `.dive-ci` or a custom path specified by `--ci-config`.

### Can I hide unmodified files in the diff view through configuration?

Yes. Add the `hide` field under the `diff` section in your YAML configuration with the value `["unmodified"]`. This corresponds to the `options.UIDiff` struct in [`cmd/dive/cli/internal/options/ui_diff.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/ui_diff.go). You can also hide `added`, `removed`, or `modified` change types using the same array syntax.

### Where does Dive store its default UI preferences?

Default UI preferences are hardcoded in [`cmd/dive/cli/internal/ui/v1/config.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/ui/v1/config.go) and are overridden by user-specific values through the `Application.V1Preferences()` method in [`cmd/dive/cli/internal/options/application.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/options/application.go). User configurations in `~/.dive.yaml` take precedence over these defaults but do not modify the source files.