openshift · agantony · Jun 22, 2026 · May 18, 2026
diff --git a/cli/command-reference/roxctl-image.adoc b/cli/command-reference/roxctl-image.adoc
@@ -6,37 +6,17 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-Commands that you can run on a specific image.
+[role="_abstract"]
+Use the `roxctl image` command to run operations on container images, including scanning for vulnerabilities, checking for policy violations, and generating Software Bill of Materials (SBOM) reports. This reference covers the command syntax, available subcommands, and configuration options.
 
-.Usage
-[source,terminal]
-----
-$ roxctl image [command] [flags]
-----
+//roxctl image overview
+include::modules/roxctl-image-overview.adoc[leveloffset=+1]
 
-.Available commands
-[cols="2,2",options="header"]
-|===
-|Command |Description
+include::modules/roxctl-image-usage.adoc[leveloffset=+2]
 
-|`check`
-|Check images for build time policy violations, and report them.
+include::modules/roxctl-image-available-commands.adoc[leveloffset=+2]
 
-|`sbom`
-|Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource.
-
-|`scan`
-|Scan the specified image, and return the scan results.
-|===
-
-
-.Options
-[cols="2,2",options="header"]
-|===
-
-|`-t`, `--timeout duration`
-|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`.
-|===
+include::modules/roxctl-image-options.adoc[leveloffset=+2]
 
 //Options inherited from the parent command
 :commandname: roxctl image
@@ -46,8 +26,20 @@ include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1]
 //roxctl image sbom
 include::modules/roxctl-image-sbom.adoc[leveloffset=+1]
 
+include::modules/roxctl-image-sbom-usage.adoc[leveloffset=+2]
+
+include::modules/roxctl-image-sbom-options.adoc[leveloffset=+2]
+
 //roxctl image scan
 include::modules/roxctl-image-scan.adoc[leveloffset=+1]
 
+include::modules/roxctl-image-scan-usage.adoc[leveloffset=+2]
+
+include::modules/roxctl-image-scan-options.adoc[leveloffset=+2]
+
 //roxctl image check
-include::modules/roxctl-image-check.adoc[leveloffset=+1]
+include::modules/roxctl-image-check.adoc[leveloffset=+1]
+
+include::modules/roxctl-image-check-usage.adoc[leveloffset=+2]
+
+include::modules/roxctl-image-check-options.adoc[leveloffset=+2]
diff --git a/modules/options-inherited-from-the-parent-command.adoc b/modules/options-inherited-from-the-parent-command.adoc
@@ -25,6 +25,7 @@ endif::[]
 [id="options-inherited-from-the-parent-command_{context}"]
 = {commandname} command options inherited from the parent command
 
+[role="_abstract"]
 The `{commandname}` command supports the following options inherited from the parent `roxctl` command:
 
 [cols="2,2",options="header"]

diff --git a/modules/roxctl-image-available-commands.adoc b/modules/roxctl-image-available-commands.adoc
@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-available-commands_{context}"]
+= Available commands
+
+[role="_abstract"]
+Available commands for the `roxctl image` command.
+
+[cols="2,2",options="header"]
+|===
+|Command |Description
+
+|`check`
+|Check images for build time policy violations, and report them.
+
+|`sbom`
+|Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource.
+
+|`scan`
+|Scan the specified image, and return the scan results.
+|===
diff --git a/modules/roxctl-image-check-options.adoc b/modules/roxctl-image-check-options.adoc
@@ -0,0 +1,64 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-check-options_{context}"]
+= Options
+
+[role="_abstract"]
+Options for the `roxctl image check` command.
+
+.Options
+[cols="5,4",options="header"]
+|===
+|Option |Description
+
+|`-c`, `--categories strings`
+|List of the policy categories that you want to run. By default, the command uses all policy categories.
+
+|`--cluster string`
+|Define the cluster name or ID that you want to use as the context for evaluation.
+
+|`--compact-output`
+|Print JSON output in a compact format. The default value is `false`.
+
+|`-f`, `--force`
+|Bypass the Central cache for the image and force a new pull from the Scanner. The default value is `false`.
+
+|`--headers strings`
+|Define headers to print in a tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS BUILD`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`.
+
+|`--headers-as-comments`
+|Print headers as comments in a CSV tabular output. The default value is `false`.
+
+|`-i`, `--image string`
+|Specify the image name and reference. For example, `nginx:latest` or `nginx@sha256:...)`.
+
+|`--junit-suite-name string`
+|Set the name of the JUnit test suite. Default value is `image-check`.
+
+|`--merge-output`
+|Merge duplicate cells in a tabular output. The default value is `false`.
+
+|`--namespace`
+|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans.
+
+|`--no-header`
+|Do not print headers for a tabular output. The default value is `false`.
+
+|`-o`, `--output string`
+|Choose the output format. Output formats include `junit`, `sarif`, `table`, `csv`, and `json`. The default value is `table`.
+
+|`-r`, `--retries int`
+|Set the number of retries before exiting as an error. The default value is `3`.
+
+|`-d`, `--retry-delay int`
+|Set the time to wait between retries in seconds. The default value is `3`.
+
+|`--row-jsonpath-expressions string`
+|Create a row from the JSON object by using JSON path expression. For more details, run the `roxctl image check --help` command.
+
+|`--send-notifications`
+|Define whether you want to send notifications if violations occur. The default value is `false`.
+|===
diff --git a/modules/roxctl-image-check-usage.adoc b/modules/roxctl-image-check-usage.adoc
@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-check-usage_{context}"]
+= roxctl image check usage
+
+[role="_abstract"]
+Usage syntax for the `roxctl image check` command.
+
+.Usage
+[source,terminal]
+----
+$ roxctl image check [flags]
+----
diff --git a/modules/roxctl-image-check.adoc b/modules/roxctl-image-check.adoc
@@ -1,69 +1,10 @@
 // Module included in the following assemblies:
 //
-// * command-reference/roxctl-image.adoc
+// * cli/command-reference/roxctl-image.adoc
 
-:_mod-docs-content-type: REFERENCE
+:_mod-docs-content-type: CONCEPT
 [id="roxctl-image-check_{context}"]
 = roxctl image check
 
-Check images for build time policy violations, and report them.
-
-.Usage
-[source,terminal]
-----
-$ roxctl image check [flags]
-----
-
-.Options
-[cols="5,4",options="header"]
-|===
-|Option |Description
-
-|`-c`, `--categories strings`
-|List of the policy categories that you want to execute. By default, all the policy categories are used.
-
-|`--cluster string`
-|Define the cluster name or ID that you want to use as the context for evaluation.
-
-|`--compact-output`
-|Print JSON output in a compact format. The default value is `false`.
-
-|`-f`, `--force`
-|Bypass the Central cache for the image and force a new pull from the Scanner. The default value is `false`.
-
-|`--headers strings`
-|Define headers to print in a tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS BUILD`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`.
-
-|`--headers-as-comments`
-|Print headers as comments in a CSV tabular output. The default value is `false`.
-
-|`-i`, `--image string`
-|Specify the image name and reference. For example, `nginx:latest` or `nginx@sha256:...)`.
-
-|`--junit-suite-name string`
-|Set the name of the JUnit test suite. Default value is `image-check`.
-
-|`--merge-output`
-|Merge duplicate cells in a tabular output. The default value is `false`.
-
-|`--namespace`
-|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans.
-
-|`--no-header`
-|Do not print headers for a tabular output. The default value is `false`.
-
-|`-o`, `--output string`
-|Choose the output format. Output formats include `junit`, `sarif`, `table`, `csv`, and `json`. The default value is `table`.
-
-|`-r`, `--retries int`
-|Set the number of retries before exiting as an error. The default value is `3`.
-
-|`-d`, `--retry-delay int`
-|Set the time to wait between retries in seconds. The default value is `3`.
-
-|`--row-jsonpath-expressions string`
-|Create a row from the JSON object by using JSON path expression. For more details, run the `roxctl image check --help` command.
-
-|`--send-notifications`
-|Define whether you want to send notifications in the event of violations. The default value is `false`.
-|===
+[role="_abstract"]
+Check images for build time policy violations, and report them.
diff --git a/modules/roxctl-image-options.adoc b/modules/roxctl-image-options.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-options_{context}"]
+= Options
+
+[role="_abstract"]
+Options for the `roxctl image` command.
+
+[cols="2,2",options="header"]
+|===
+|Option |Description
+
+|`-t`, `--timeout duration`
+|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`.
+|===
diff --git a/modules/roxctl-image-overview.adoc b/modules/roxctl-image-overview.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="roxctl-image-overview_{context}"]
+= roxctl image
+
+[role="_abstract"]
+Commands that you can run on a specific image.
diff --git a/modules/roxctl-image-sbom-options.adoc b/modules/roxctl-image-sbom-options.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-sbom-options_{context}"]
+= Options
+
+[role="_abstract"]
+Options for the `roxctl image sbom` command.
+
+.Options
+[cols="5,4",options="header"]
+|===
+|Option |Description
+
+|`--cluster` string
+|Cluster name or ID that you want to delegate the image scan to.
+
+|`--namespace` string
+|Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets for accessing the image registry.
+
+|`-f, --force`
+|Bypass Central's cache for the image and force a new pull from the scanner. The default is `false`.
+
+|`-d, --retry-delay integer`
+|Sets the time to wait between retries in seconds. The default is 3.
+
+|`-i, --image string`
+|Image name and reference, for example, `nginx:latest` or `nginx@sha256:...`.
+
+|`-r, --retries integer`
+|Sets the number of times that Scanner V4 should retry before exiting with an error. The default is 3.
+|===
diff --git a/modules/roxctl-image-sbom-usage.adoc b/modules/roxctl-image-sbom-usage.adoc
@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * cli/command-reference/roxctl-image.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="roxctl-image-sbom-usage_{context}"]
+= roxctl image sbom usage
+
+[role="_abstract"]
+Usage syntax for the `roxctl image sbom` command.
+
+.Usage
+[source,terminal]
+----
+$ roxctl image sbom [flags]
+----
diff --git a/modules/roxctl-image-sbom.adoc b/modules/roxctl-image-sbom.adoc
@@ -1,39 +1,10 @@
 // Module included in the following assemblies:
 //
-// * command-reference/roxctl-image.adoc
+// * cli/command-reference/roxctl-image.adoc
 
-:_mod-docs-content-type: REFERENCE
+:_mod-docs-content-type: CONCEPT
 [id="roxctl-image-sbom_{context}"]
 = roxctl image sbom
 
-Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource.
-
-.Usage
-[source,terminal]
-----
-$ roxctl image sbom [flags]
-----
-
-.Options
-[cols="5,4",options="header"]
-|===
-|Option |Description
-
-|`--cluster` string
-|Cluster name or ID that you want to delegate the image scan to.
-
-|`--namespace` string
-|Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets for accessing the image registry.
-
-|`-f, --force`
-|Bypass Central's cache for the image and force a new pull from the scanner. The default is `false`.
-
-|`-d, --retry-delay integer`
-|Sets the time to wait between retries in seconds. The default is 3.
-
-|`-i, --image string`
-|Image name and reference, for example, `nginx:latest` or `nginx@sha256:...`.
-
-|`-r, --retries integer`
-|Sets the number of times that Scanner V4 should retry before exiting with an error. The default is 3.
-|===
+[role="_abstract"]
+Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource.