What Are the Main Command-Line Entry Points for Dive?

The three main command-line entry points for Dive are dive <image> for analyzing existing Docker or OCI images, dive build for constructing images from Dockerfiles and immediately analyzing them, and utility commands (version and config) for managing application metadata and settings.

Dive is an open-source Go application maintained in the wagoodman/dive repository that visualizes Docker image layers and file system efficiency. Understanding these command-line entry points for Dive is essential for integrating the tool into CI/CD pipelines, local development workflows, and container optimization processes.

Overview of the CLI Architecture

The executable entry point resides in cmd/dive/main.go, which initializes a clio application framework and delegates command registration to cmd/dive/cli/cli.go. The architecture separates command definitions (root.go, build.go) from execution adapters (cmd/dive/cli/internal/command/adapter/*.go), allowing the same analysis pipeline to process images regardless of their source.

The Three Primary Entry Points

1. Image Analysis: dive <image>

The most common entry point is the root command defined in cmd/dive/cli/internal/command/root.go. It accepts a single required argument: the image identifier (name, tag, or digest).

When invoked, the RunE handler in root.go parses the image argument, initializes the image resolver via dive.GetImageResolver, and calls adapter.ImageResolver(...).Fetch to retrieve the image layers. The resolved image then passes to the run() function, which performs the analysis, optional CI checks, and publishes results to the internal event bus for the terminal UI.

2. Build Integration: dive build [docker-build-flags]

The build sub-command, implemented in cmd/dive/cli/internal/command/build.go, functions as a thin wrapper around docker build. It accepts standard Docker build flags and a context path.

Rather than fetching an existing image, this entry point invokes adapter.ImageResolver(...).Build with the raw build arguments. Upon successful image creation, it forwards the resulting image ID to the same run() function used by the root command, ensuring consistent analysis behavior whether the image is pulled or freshly built.

3. Utility Commands: version and config

Dive leverages the clio framework to inject standard utility commands. In cmd/dive/cli/cli.go, the application registers:

• clio.VersionCommand(id) → dive version
• clio.ConfigCommand(app, nil) → dive config

These commands bypass Dive's image analysis logic entirely. The version command outputs static build information, while config loads or saves the application's YAML configuration files.

Command Registration and Wiring

The create() function in cmd/dive/cli/cli.go assembles the command hierarchy by attaching sub-commands to the root Cobra command:

// cmd/dive/cli/cli.go
func create(id clio.Identification) (clio.Application, *cobra.Command) {
    // …
    rootCmd := command.Root(app)

    rootCmd.AddCommand(
        clio.VersionCommand(id),        // `dive version`
        clio.ConfigCommand(app, nil),   // `dive config`
        command.Build(app),             // `dive build …`
    )
    // …
}

This registration pattern ensures that dive <image> remains the default behavior while explicitly namespacing build and utility functionality.

Execution Flow by Entry Point

Each entry point follows a distinct path through the codebase:

• dive <image>: main.go → cli.Application() → command.Root() → RunE handler → dive.GetImageResolver → adapter.ImageResolver(...).Fetch → run() → event bus → UI layer.

• dive build …: main.go → cli.Application() → command.Build() → RunE handler → adapter.ImageResolver(...).Build → run() → event bus → UI layer.

• Utility commands: Directly handled by clio framework methods; skip image resolution and analysis pipeline.

Practical Usage Examples

# Analyze an existing image from a registry

dive alpine:3.18

# Build from a Dockerfile and analyze the result

dive build -t myapp:latest .

# Display the compiled binary version and build info

dive version

# View or modify the application configuration

dive config -c ./dive.yaml

Summary

• dive <image> is the primary entry point for analyzing existing Docker or OCI images, implemented in cmd/dive/cli/internal/command/root.go.
• dive build constructs images from Dockerfiles before analysis, implemented in cmd/dive/cli/internal/command/build.go.
• dive version and dive config are clio framework utilities for metadata and configuration management.
• All entry points are registered in cmd/dive/cli/cli.go via the create() function.
• The analysis pipeline converges at the run() function regardless of whether the image is fetched or built.

Frequently Asked Questions

What is the difference between dive <image> and dive build?

dive <image> analyzes existing images pulled from registries or present locally, while dive build first constructs an image from a Dockerfile using standard Docker build arguments, then immediately analyzes the resulting image. Both commands eventually call the same run() function in the Dive analysis pipeline.

How does Dive resolve images for different container engines?

According to the wagoodman/dive source code, the dive.GetImageResolver function in dive/image/resolver.go abstracts provider-specific logic for Docker, Podman, and OCI archives. The adapters in cmd/dive/cli/internal/command/adapter/*.go bridge these resolvers to the CLI commands, allowing dive <image> and dive build to work across multiple container runtimes.

Where is the main entry point code located in the Dive repository?

The program entry point is cmd/dive/main.go, which creates the clio application. Command registration occurs in cmd/dive/cli/cli.go, while specific command implementations reside in cmd/dive/cli/internal/command/root.go (for dive <image>) and cmd/dive/cli/internal/command/build.go (for dive build).

Can I use Dive with Podman instead of Docker?

Yes. The image resolver architecture in dive/image/resolver.go supports multiple container engines. When you run dive <image> or dive build, the tool uses provider-specific adapters to fetch or build images using the underlying engine configured in your environment, including Podman support.

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