Use the DHI CLI

Table of contents

The docker dhi command-line interface (CLI) is a tool for managing Docker Hardened Images:

Browse the catalog of available DHI images and their metadata
Mirror DHI images to your Docker Hub organization
Create and manage customizations of DHI images
Generate authentication for enterprise package repositories
Monitor customization builds

Installation

The docker dhi CLI is available in Docker Desktop version 4.65 and later. You can also install the standalone dhictl binary.

Docker Desktop

The docker dhi command is included in Docker Desktop 4.65 and later. No additional installation is required.

Standalone binary

Download the dhictl binary for your platform from the releases page.
Move it to a directory in your PATH:
- mv dhictl /usr/local/bin/ on Linux and macOS
- Move dhictl.exe to a directory in your PATH on Windows

Usage

Every command has built-in help accessible with the --help flag:

docker dhi --help
docker dhi catalog list --help

Browse the DHI catalog

List all available DHI images:

docker dhi catalog list

Filter by type, name, or compliance:

docker dhi catalog list --type image
docker dhi catalog list --filter golang
docker dhi catalog list --fips
docker dhi catalog list --stig

Get details of a specific image, including available tags and CVE counts:

docker dhi catalog get <image-name>

Mirror DHI images DHI Select & DHI Enterprise

Start mirroring one or more DHI images to your Docker Hub organization:

docker dhi mirror start --org my-org \
  -r dhi/golang,my-org/dhi-golang \
  -r dhi/nginx,my-org/dhi-nginx \
  -r dhi/prometheus-chart,my-org/dhi-prometheus-chart

Mirror with dependencies:

docker dhi mirror start --org my-org -r golang --dependencies

List mirrored images in your organization:

docker dhi mirror list --org my-org

Filter mirrored images by name or type:

docker dhi mirror list --org my-org --filter python
docker dhi mirror list --org my-org --type image
docker dhi mirror list --org my-org --type helm-chart

Stop mirroring one or more images:

docker dhi mirror stop dhi-golang --org my-org
docker dhi mirror stop dhi-python dhi-golang --org my-org

Stop mirroring and delete the repositories:

docker dhi mirror stop dhi-golang --org my-org --delete
docker dhi mirror stop dhi-golang --org my-org --delete --force

Customize DHI images DHI Select & DHI Enterprise

The CLI can be used to create and manage DHI image customizations. For detailed instructions on creating customizations, including the YAML syntax and available options, see Customize a Docker Hardened Image.

Quick reference for CLI commands:

# Prepare a customization scaffold
docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  --output my-customization.yaml

# Create a customization
docker dhi customization create my-customization.yaml --org my-org

# List customizations
docker dhi customization list --org my-org

# Filter customizations by name, repository, or source
docker dhi customization list --org my-org --filter git
docker dhi customization list --org my-org --repo dhi-golang
docker dhi customization list --org my-org --source golang

# Get a customization
docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml

# Update a customization
docker dhi customization edit my-customization.yaml --org my-org

# Delete a customization
docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org

# Delete without confirmation prompt
docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org --yes

Enterprise package authentication DHI Enterprise

Generate authentication credentials for accessing the enterprise hardened package repository. This is used when configuring your package manager to install compliance-specific packages in your own images. For detailed instructions, see Enterprise repository.

docker dhi auth apk

Monitor customization builds DHI Select & DHI Enterprise

List builds for a customization:

docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org
docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org --json

Get details of a specific build:

docker dhi customization build get my-org/dhi-golang "golang with git" <build-id> --org my-org
docker dhi customization build get my-org/dhi-golang "golang with git" <build-id> --org my-org --json

View build logs:

docker dhi customization build logs my-org/dhi-golang "golang with git" <build-id> --org my-org
docker dhi customization build logs my-org/dhi-golang "golang with git" <build-id> --org my-org --json

JSON output

Most list and get commands support a --json flag for machine-readable output:

docker dhi catalog list --json
docker dhi catalog get golang --json
docker dhi mirror list --org my-org --json
docker dhi mirror start --org my-org -r golang --json
docker dhi customization list --org my-org --json
docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org --json

Configuration

The docker dhi CLI can be configured with a YAML file located at:

$HOME/.config/dhictl/config.yaml on Linux and macOS
%USERPROFILE%\.config\dhictl\config.yaml on Windows

If $XDG_CONFIG_HOME is set, the configuration file is located at $XDG_CONFIG_HOME/dhictl/config.yaml (see the XDG Base Directory Specification).

Available configuration options:

Option	Environment Variable	Description
`org`	`DHI_ORG`	Default Docker Hub organization for mirror and customization commands.
`api_token`	`DHI_API_TOKEN`	Docker token for authentication. You can generate a token in your Docker Hub account settings.

Environment variables take precedence over configuration file values.

Ask me about Docker