diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md index ab1361db7f..27dd791bce 100644 --- a/content/manuals/dhi/how-to/cli.md +++ b/content/manuals/dhi/how-to/cli.md @@ -2,11 +2,11 @@ title: Use the DHI CLI linkTitle: Use the CLI weight: 50 -keywords: dhictl, CLI, command line, docker hardened images -description: Learn how to install and use dhictl, the command-line interface for managing Docker Hardened Images. +keywords: docker dhi, CLI, command line, docker hardened images +description: Learn how to install and use docker dhi, the command-line interface for managing Docker Hardened Images. --- -`dhictl` is a command-line interface (CLI) tool for managing Docker Hardened Images: +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 @@ -15,23 +15,14 @@ description: Learn how to install and use dhictl, the command-line interface for ## Installation -`dhictl` will be available by default on [Docker Desktop](https://docs.docker.com/desktop/) soon. -In the meantime, you can install `dhictl` manually as a Docker CLI plugin or as a standalone binary. +The `docker dhi` CLI is available in [Docker Desktop](https://docs.docker.com/desktop/) version 4.65 and later. +You can also install the standalone `dhictl` binary. -### Docker CLI Plugin +### Docker Desktop -1. Download the `dhictl` binary for your platform from the [releases](https://github.com/docker-hardened-images/dhictl/releases) page. -2. Rename the binary: - - `docker-dhi` on _Linux_ and _macOS_ - - `docker-dhi.exe` on _Windows_ -3. Copy it to the CLI plugins directory: - - `$HOME/.docker/cli-plugins` on _Linux_ and _macOS_ - - `%USERPROFILE%\.docker\cli-plugins` on _Windows_ -4. Make it executable on _Linux_ and _macOS_: - - `chmod +x $HOME/.docker/cli-plugins/docker-dhi` -5. Run `docker dhi` to verify the installation. +The `docker dhi` command is included in Docker Desktop 4.65 and later. No additional installation is required. -### Standalone Binary +### Standalone binary 1. Download the `dhictl` binary for your platform from the [releases](https://github.com/docker-hardened-images/dhictl/releases) page. @@ -41,64 +32,82 @@ In the meantime, you can install `dhictl` manually as a Docker CLI plugin or as ## Usage -> [!NOTE] -> -> The following examples use `dhictl` to reference the CLI tool. Depending on -> your installation, you may need to replace `dhictl` with `docker dhi`. - Every command has built-in help accessible with the `--help` flag: ```bash -dhictl --help -dhictl catalog list --help +docker dhi --help +docker dhi catalog list --help ``` -### Browse the DHI Catalog +### Browse the DHI catalog List all available DHI images: ```bash -dhictl catalog list +docker dhi catalog list ``` Filter by type, name, or compliance: ```bash -dhictl catalog list --type image -dhictl catalog list --filter golang -dhictl catalog list --fips +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: ```bash -dhictl catalog get +docker dhi catalog get ``` -### Mirror DHI Images {tier="DHI Select & DHI Enterprise"} +### Mirror DHI images {tier="DHI Select & DHI Enterprise"} Start mirroring one or more DHI images to your Docker Hub organization: ```bash -dhictl mirror start --org my-org \ +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: + +```bash +docker dhi mirror start --org my-org -r golang --dependencies +``` + List mirrored images in your organization: ```bash -dhictl mirror list --org my-org +docker dhi mirror list --org my-org ``` -Stop mirroring an image: +Filter mirrored images by name or type: ```bash -dhictl mirror stop --org my-org dhi-golang +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 ``` -### Customize DHI Images {tier="DHI Select & DHI Enterprise"} +Stop mirroring one or more images: + +```bash +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: + +```bash +docker dhi mirror stop dhi-golang --org my-org --delete +docker dhi mirror stop dhi-golang --org my-org --delete --force +``` + +### Customize DHI images {tier="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 @@ -108,29 +117,37 @@ Quick reference for CLI commands: ```bash # Prepare a customization scaffold -dhictl customization prepare --org my-org golang 1.25 \ +docker dhi customization prepare golang 1.25 \ + --org my-org \ --destination my-org/dhi-golang \ --name "golang with git" \ - --tag-suffix "_git" \ --output my-customization.yaml # Create a customization -dhictl customization create --org my-org my-customization.yaml +docker dhi customization create my-customization.yaml --org my-org # List customizations -dhictl customization list --org my-org +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 -dhictl customization get --org my-org my-org/dhi-golang "golang with git" --output my-customization.yaml +docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml # Update a customization -dhictl customization edit --org my-org my-customization.yaml +docker dhi customization edit my-customization.yaml --org my-org # Delete a customization -dhictl customization delete --org my-org my-org/dhi-golang "golang with git" +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 {tier="DHI Enterprise"} +### Enterprise package authentication {tier="DHI Enterprise"} Generate authentication credentials for accessing the enterprise hardened package repository. This is used when configuring your package manager to @@ -139,42 +156,48 @@ instructions, see [Enterprise repository](./hardened-packages.md#enterprise-repository). ```bash -dhictl auth apk +docker dhi auth apk ``` -### Monitor Customization Builds {tier="DHI Select & DHI Enterprise"} +### Monitor customization builds {tier="DHI Select & DHI Enterprise"} List builds for a customization: ```bash -dhictl customization build list --org my-org my-org/dhi-golang "golang with git" +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: ```bash -dhictl customization build get --org my-org my-org/dhi-golang "golang with git" +docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org +docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org --json ``` View build logs: ```bash -dhictl customization build logs --org my-org my-org/dhi-golang "golang with git" +docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org +docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org --json ``` -### JSON Output +### JSON output Most list and get commands support a `--json` flag for machine-readable output: ```bash -dhictl catalog list --json -dhictl mirror list --org my-org --json -dhictl customization list --org my-org --json +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 -`dhictl` can be configured with a YAML file located at: +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_ diff --git a/data/cli/dhi/docker_dhi_customization_edit.yaml b/data/cli/dhi/docker_dhi_customization_edit.yaml index ca05bc1703..bdf4c89e55 100644 --- a/data/cli/dhi/docker_dhi_customization_edit.yaml +++ b/data/cli/dhi/docker_dhi_customization_edit.yaml @@ -1,5 +1,5 @@ command: docker dhi customization edit -aliases: docker dhi customization edit, docker dhi customization update +aliases: dhi customization edit, dhi customization update short: Edit an existing customization from YAML file long: | Edit an existing Docker Hardened Images customization using a YAML file as input. The file should contain the complete customization structure with an 'id' field to identify which customization to update. diff --git a/data/cli/dhi/docker_dhi_customization_prepare.yaml b/data/cli/dhi/docker_dhi_customization_prepare.yaml index 555645b320..acfbb56d59 100644 --- a/data/cli/dhi/docker_dhi_customization_prepare.yaml +++ b/data/cli/dhi/docker_dhi_customization_prepare.yaml @@ -43,16 +43,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: tag-suffix - shorthand: t - value_type: string - description: Tag suffix for the customized image - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false inherited_options: - option: org value_type: string diff --git a/data/cli/dhi/docker_dhi_mirror_list.yaml b/data/cli/dhi/docker_dhi_mirror_list.yaml index 58d3f93f2b..cb3cb21b08 100644 --- a/data/cli/dhi/docker_dhi_mirror_list.yaml +++ b/data/cli/dhi/docker_dhi_mirror_list.yaml @@ -7,19 +7,19 @@ long: |- Examples: # List all mirrored repositories - dhictl mirror list --org myorg + docker dhi mirror list --org myorg # List only image repositories - dhictl mirror list --org myorg --type image + docker dhi mirror list --org myorg --type image # List only helm chart repositories - dhictl mirror list --org myorg --type helm-chart + docker dhi mirror list --org myorg --type helm-chart # Search for a specific repository by name - dhictl mirror list --org myorg --filter dhi-python + docker dhi mirror list --org myorg --filter dhi-python # Output in JSON format - dhictl mirror list --org myorg --json + docker dhi mirror list --org myorg --json usage: docker dhi mirror list pname: docker dhi mirror plink: docker_dhi_mirror.yaml diff --git a/data/cli/dhi/docker_dhi_mirror_start.yaml b/data/cli/dhi/docker_dhi_mirror_start.yaml index cc9cda4ff7..cfd12c7398 100644 --- a/data/cli/dhi/docker_dhi_mirror_start.yaml +++ b/data/cli/dhi/docker_dhi_mirror_start.yaml @@ -15,12 +15,12 @@ long: |- Examples: # These are all equivalent (assuming --org myorg): - dhictl mirror start --org myorg -r dhi/golang,myorg/dhi-golang - dhictl mirror start --org myorg -r golang,dhi-golang - dhictl mirror start --org myorg -r golang + docker dhi mirror start --org myorg -r dhi/golang,myorg/dhi-golang + docker dhi mirror start --org myorg -r golang,dhi-golang + docker dhi mirror start --org myorg -r golang # Mirror multiple repositories - dhictl mirror start --org myorg -r golang -r python + docker dhi mirror start --org myorg -r golang -r python usage: docker dhi mirror start pname: docker dhi mirror plink: docker_dhi_mirror.yaml diff --git a/data/cli/dhi/docker_dhi_mirror_stop.yaml b/data/cli/dhi/docker_dhi_mirror_stop.yaml index 555bb7e411..ce69dd0db3 100644 --- a/data/cli/dhi/docker_dhi_mirror_stop.yaml +++ b/data/cli/dhi/docker_dhi_mirror_stop.yaml @@ -1,29 +1,52 @@ command: docker dhi mirror stop -short: Stop mirroring a Docker Hardened Image +short: Stop mirroring one or more Docker Hardened Images long: |- - Stop mirroring a Docker Hardened Image repository. + Stop mirroring one or more Docker Hardened Image repositories. - The repository can be specified as: - - Just the repository name (e.g., dhi-python) - uses --org flag or config - - Full path with org (e.g., myorg/dhi-python) - org must match --org flag or config + Multiple repositories can be specified as positional arguments. + + Each repository can be specified as: + - namespace/name (e.g., myorg/dhi-python) - org must match --org flag or config + - name only (e.g., dhi-python) - the namespace can be omitted for simplicity + and the command will default to the current org automatically Examples: - # Stop mirroring using --org flag - dhictl mirror stop dhi-python --org myorg + # Stop mirroring a single repository + docker dhi mirror stop myorg/dhi-python --org myorg - # Stop mirroring with full path (org must match) - dhictl mirror stop myorg/dhi-python --org myorg + # Stop mirroring using just the name (defaults to current org) + docker dhi mirror stop dhi-python --org myorg - # Stop mirroring and delete the repository - dhictl mirror stop dhi-python --org myorg --delete -usage: docker dhi mirror stop + # Stop mirroring multiple repositories + docker dhi mirror stop dhi-python dhi-golang dhi-node --org myorg + + # Stop mirroring and delete the repositories + docker dhi mirror stop dhi-python dhi-golang --org myorg --delete + + # Stop mirroring, delete without confirmation prompt + docker dhi mirror stop dhi-python dhi-golang --org myorg --delete --force + + # Stop mirroring all repositories matching a filter (using shell substitution) + docker dhi mirror stop $(docker dhi mirror list --org myorg --filter golang --json | jq -r '.[].repository') --org myorg +usage: docker dhi mirror stop [repository...] pname: docker dhi mirror plink: docker_dhi_mirror.yaml options: - option: delete value_type: bool default_value: "false" - description: Delete the repository after stopping mirroring + description: Delete the repositories after stopping mirroring + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: force + shorthand: f + value_type: bool + default_value: "false" + description: Skip confirmation prompt when deleting repositories deprecated: false hidden: false experimental: false