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

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. 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, 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:

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

CI Configuration Options

Continuous integration settings are managed in 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, 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 aggregates four sub-components that customize the terminal interface behavior.

Keybindings

Defined in 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:

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

File Tree

Configured in 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:

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

UI defaults are sourced from cmd/dive/cli/internal/ui/v1/config.go and converted via the Application.V1Preferences() method:

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:

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:

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

Example my-ci-rules.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:

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:

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 control container engines (Docker/Podman) and error tolerance.
• CI mode settings in 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, ui_diff.go, ui_filetree.go, and ui_layers.go.
• The V1Preferences() method in 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 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 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. 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 and are overridden by user-specific values through the Application.V1Preferences() method in cmd/dive/cli/internal/options/application.go. User configurations in ~/.dive.yaml take precedence over these defaults but do not modify the source files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}