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

> Discover the main command-line entry points for Dive: analyze images with `dive <image>`, build and analyze with `dive build`, or manage settings with utility commands.

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

---

**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`](https://github.com/wagoodman/dive/blob/main/cmd/dive/main.go), which initializes a **clio** application framework and delegates command registration to [`cmd/dive/cli/cli.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/cli.go). The architecture separates command definitions ([`root.go`](https://github.com/wagoodman/dive/blob/main/root.go), [`build.go`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/cli.go) assembles the command hierarchy by attaching sub-commands to the root Cobra command:

```go
// 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`](https://github.com/wagoodman/dive/blob/main/main.go) → `cli.Application()` → `command.Root()` → **RunE** handler → `dive.GetImageResolver` → `adapter.ImageResolver(...).Fetch` → `run()` → event bus → UI layer.

- **`dive build …`**: [`main.go`](https://github.com/wagoodman/dive/blob/main/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

```bash

# 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`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/command/root.go).
- **`dive build`** constructs images from Dockerfiles before analysis, implemented in [`cmd/dive/cli/internal/command/build.go`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/cmd/dive/main.go), which creates the **clio** application. Command registration occurs in [`cmd/dive/cli/cli.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/cli.go), while specific command implementations reside in [`cmd/dive/cli/internal/command/root.go`](https://github.com/wagoodman/dive/blob/main/cmd/dive/cli/internal/command/root.go) (for `dive <image>`) and [`cmd/dive/cli/internal/command/build.go`](https://github.com/wagoodman/dive/blob/main/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`](https://github.com/wagoodman/dive/blob/main/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.