doc: Update legacy cli docs (Supersedes #723) (#724)

frewilhelm · ocmbot[bot] · web-flow · commit 1bf8bf3a6ff2 · 2026-02-24T12:20:27.000+01:00
Update OCM CLI documentation for new release in folder
content_versioned/version-legacy

---------

Signed-off-by: Frederic Wilhelm &lt;frederic.wilhelm@sap.com&gt;
Co-authored-by: ocmbot[bot] &lt;125909804+ocmbot[bot]@users.noreply.github.com&gt;
diff --git a/.github/config/wordlist.txt b/.github/config/wordlist.txt
@@ -132,6 +132,7 @@ fluxvaluessource
 foldername
 forwardspec
 frontend
+fulcio
 gapped
 gav
 getinexpensivecontentversionidentity
@@ -307,6 +308,7 @@ reconciledversion
 reconciler
 refcount
 referencesconfig
+rekor
 relativeocireference
 releaser
 replicatedrepositoryurl
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/_index.md b/content_versioned/version-legacy/docs/reference/ocm-cli/_index.md
@@ -309,6 +309,26 @@ The value can be a simple type or a JSON/YAML string for complex values
   the backend and descriptor updated will be persisted on AddVersion
   or closing a provided existing component version.
 
+- <code>ocm.software/ocm/api/ocm/extensions/attrs/maxworkers</code> [<code>maxworkers</code>]: *integer* or *"auto"*
+
+  Specifies the maximum number of concurrent workers to use for resource and source,
+  as well as reference transfer operations.
+  
+  Supported values:
+    - A positive integer: use exactly that number of workers.
+    - The string "auto": automatically use the number of logical CPU cores.
+    - Zero or omitted: fall back to single-worker mode (1). This is the default.
+      This mode guarantees deterministic ordering of operations.
+  
+  Precedence:
+    1. Attribute set in the current OCM context.
+    2. Environment variable OCM_TRANSFER_WORKER_COUNT.
+    3. Default value (1).
+  
+  WARNING: This is an experimental feature and may cause unexpected behavior
+  depending on workload concurrency. Values above 1 may result in non-deterministic
+  transfer ordering.
+
 - <code>ocm.software/ocm/oci/preferrelativeaccess</code> [<code>preferrelativeaccess</code>]: *bool*
 
   If an artifact blob is uploaded to the technical repository
@@ -317,6 +337,12 @@ The value can be a simple type or a JSON/YAML string for complex values
 
 - <code>ocm.software/signing/sigstore</code> [<code>sigstore</code>]: *sigstore config* Configuration to use for sigstore based signing.
 
+  
+  Configuration applies to <code>sigstore</code> (legacy) and <code>sigstore-v2</code> signing algorithms.
+  The algorithms affect how signatures are stored in Rekor:
+  - <code>sigstore</code>: stores only public key in Rekor entry (non-compliant Sigstore Bundle spec).
+  - <code>sigstore-v2</code>: stores Fulcio certificate in Rekor entry (compliant Sigstore Bundle spec).
+  
   The following fields are used.
   - *<code>fulcioURL</code>* *string*  default is https://fulcio.sigstore.dev
   - *<code>rekorURL</code>* *string*  default is https://rekor.sigstore.dev
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/add/add_componentversions.md b/content_versioned/version-legacy/docs/reference/ocm-cli/add/add_componentversions.md
@@ -207,9 +207,6 @@ The uploader name may be a path expression with the following possibilities:
     
     sub namespace of the form <code>&lt;plugin name>/&lt;handler></code>
 
-  - <code>plugin/jfrog/JFrogHelm</code>: 
-    upload artifacts to JFrog HELM repositories by using the JFrog REST API.
-
 
 
 See [ocm ocm-uploadhandlers]({{< relref "docs/reference/ocm-cli/help/ocm-uploadhandlers.md" >}}) for further details on using
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_artifacts.md b/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_artifacts.md
@@ -20,6 +20,7 @@ ocm download artifacts [<options>]  {<artifact>}
       --dirtree          extract as effective filesystem content
   -h, --help             help for artifacts
       --layers ints      extract dedicated layers
+      --oci-layout       download as OCI Image Layout (blobs in blobs/<algorithm>/<encoded>)
   -O, --outfile string   output file or directory
       --repo string      repository name or spec
   -t, --type string      archive format (directory, tar, tgz) (default "directory")
@@ -29,10 +30,14 @@ ocm download artifacts [<options>]  {<artifact>}
 
 
 Download artifacts from an OCI registry. The result is stored in
-artifact set format, without the repository part
+artifact set format, without the repository part.
 
 The files are named according to the artifact repository name.
 
+By default, blobs are stored in OCM artifact set format (blobs/<algorithm>.<encoded>).
+Use --oci-layout to store blobs in OCI Image Layout format (blobs/<algorithm>/<encoded>)
+for compatibility with tools that expect the OCI Image Layout Specification.
+
 
 If the repository/registry option is specified, the given names are interpreted
 relative to the specified registry using the syntax
@@ -74,6 +79,15 @@ dedicated layers, only. Option <code>--dirtree</code> expects the artifact to
 be a layered filesystem (for example OCI Image) and provided the effective
 filesystem content.
 
+Option <code>--oci-layout</code> changes the blob storage structure in the downloaded
+artifact. Without this option, blobs are stored in a flat directory at
+<code>blobs/&lt;algorithm&gt;.&lt;encoded&gt;</code> (e.g., <code>blobs/sha256.abc123...</code>).
+With this option, blobs are stored in a nested directory structure at
+<code>blobs/&lt;algorithm&gt;/&lt;encoded&gt;</code> (e.g., <code>blobs/sha256/abc123...</code>)
+as specified by the OCI Image Layout Specification
+(see <a href="https://github.com/opencontainers/image-spec/blob/main/image-layout.md">
+https://github.com/opencontainers/image-spec/blob/main/image-layout.md</a>).
+
 
 The <code>--type</code> option accepts a file format for the
 target archive to use. It is only evaluated if the target 
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_cli.md b/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_cli.md
@@ -19,6 +19,7 @@ ocm download cli [<options>]  [<component> {<name> { <key>=<value> }}]
 ```
   -c, --constraints constraints   version constraint
   -h, --help                      help for cli
+      --oci-layout                download OCI artifacts in OCI Image Layout format (blobs/<algorithm>/<encoded>)
   -O, --outfile string            output file or directory
   -p, --path                      lookup executable in PATH
       --repo string               repository name or spec
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_resources.md b/content_versioned/version-legacy/docs/reference/ocm-cli/download/download_resources.md
@@ -25,6 +25,7 @@ ocm download resources [<options>]  <component> {<name> { <key>=<value> }}
   -h, --help                        help for resources
       --latest                      restrict component versions to latest
       --lookup stringArray          repository name or spec for closure lookup fallback
+      --oci-layout                  download OCI artifacts in OCI Image Layout format (blobs/<algorithm>/<encoded>)
   -O, --outfile string              output file or directory
   -r, --recursive                   follow component reference nesting
       --repo string                 repository name or spec
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/help/attributes.md b/content_versioned/version-legacy/docs/reference/ocm-cli/help/attributes.md
@@ -207,6 +207,26 @@ OCM library:
   the backend and descriptor updated will be persisted on AddVersion
   or closing a provided existing component version.
 
+- <code>ocm.software/ocm/api/ocm/extensions/attrs/maxworkers</code> [<code>maxworkers</code>]: *integer* or *"auto"*
+
+  Specifies the maximum number of concurrent workers to use for resource and source,
+  as well as reference transfer operations.
+  
+  Supported values:
+    - A positive integer: use exactly that number of workers.
+    - The string "auto": automatically use the number of logical CPU cores.
+    - Zero or omitted: fall back to single-worker mode (1). This is the default.
+      This mode guarantees deterministic ordering of operations.
+  
+  Precedence:
+    1. Attribute set in the current OCM context.
+    2. Environment variable OCM_TRANSFER_WORKER_COUNT.
+    3. Default value (1).
+  
+  WARNING: This is an experimental feature and may cause unexpected behavior
+  depending on workload concurrency. Values above 1 may result in non-deterministic
+  transfer ordering.
+
 - <code>ocm.software/ocm/oci/preferrelativeaccess</code> [<code>preferrelativeaccess</code>]: *bool*
 
   If an artifact blob is uploaded to the technical repository
@@ -215,6 +235,12 @@ OCM library:
 
 - <code>ocm.software/signing/sigstore</code> [<code>sigstore</code>]: *sigstore config* Configuration to use for sigstore based signing.
 
+  
+  Configuration applies to <code>sigstore</code> (legacy) and <code>sigstore-v2</code> signing algorithms.
+  The algorithms affect how signatures are stored in Rekor:
+  - <code>sigstore</code>: stores only public key in Rekor entry (non-compliant Sigstore Bundle spec).
+  - <code>sigstore-v2</code>: stores Fulcio certificate in Rekor entry (compliant Sigstore Bundle spec).
+  
   The following fields are used.
   - *<code>fulcioURL</code>* *string*  default is https://fulcio.sigstore.dev
   - *<code>rekorURL</code>* *string*  default is https://rekor.sigstore.dev
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/help/ocm-uploadhandlers.md b/content_versioned/version-legacy/docs/reference/ocm-cli/help/ocm-uploadhandlers.md
@@ -90,9 +90,6 @@ The following handler names are possible:
     
     sub namespace of the form <code>&lt;plugin name>/&lt;handler></code>
 
-  - <code>plugin/jfrog/JFrogHelm</code>: 
-    upload artifacts to JFrog HELM repositories by using the JFrog REST API.
-
 
 
 See [ocm ocm-uploadhandlers]({{< relref "docs/reference/ocm-cli/help/ocm-uploadhandlers.md" >}}) for further details on using
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/sign/sign_componentversions.md b/content_versioned/version-legacy/docs/reference/ocm-cli/sign/sign_componentversions.md
@@ -122,6 +122,7 @@ The following signing types are supported with option <code>--algorithm</code>:
   - <code>rsa-signingservice</code>
   - <code>rsapss-signingservice</code>
   - <code>sigstore</code>
+  - <code>sigstore-v2</code>
 
 
 The following normalization modes are supported with option <code>--normalization</code>:
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/transfer/transfer_commontransportarchive.md b/content_versioned/version-legacy/docs/reference/ocm-cli/transfer/transfer_commontransportarchive.md
@@ -159,9 +159,6 @@ The uploader name may be a path expression with the following possibilities:
     
     sub namespace of the form <code>&lt;plugin name>/&lt;handler></code>
 
-  - <code>plugin/jfrog/JFrogHelm</code>: 
-    upload artifacts to JFrog HELM repositories by using the JFrog REST API.
-
 
 
 See [ocm ocm-uploadhandlers]({{< relref "docs/reference/ocm-cli/help/ocm-uploadhandlers.md" >}}) for further details on using
diff --git a/content_versioned/version-legacy/docs/reference/ocm-cli/transfer/transfer_componentversions.md b/content_versioned/version-legacy/docs/reference/ocm-cli/transfer/transfer_componentversions.md
@@ -214,9 +214,6 @@ The uploader name may be a path expression with the following possibilities:
     
     sub namespace of the form <code>&lt;plugin name>/&lt;handler></code>
 
-  - <code>plugin/jfrog/JFrogHelm</code>: 
-    upload artifacts to JFrog HELM repositories by using the JFrog REST API.
-
 
 
 See [ocm ocm-uploadhandlers]({{< relref "docs/reference/ocm-cli/help/ocm-uploadhandlers.md" >}}) for further details on using
