From 4dac5295a19fb2fde2cb722181dee2acef31ca7b Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Thu, 17 Apr 2025 14:50:58 -0400
Subject: [PATCH 1/5] Add descriptions and examples for buildx history commands

Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>
---
 docs/reference/buildx_history_export.md       | 28 ++++++++++++
 docs/reference/buildx_history_import.md       | 25 +++++++++++
 docs/reference/buildx_history_inspect.md      | 12 +++++
 .../buildx_history_inspect_attachment.md      | 21 +++++++++
 docs/reference/buildx_history_logs.md         | 31 +++++++++++++
 docs/reference/buildx_history_ls.md           | 45 +++++++++++++++++++
 docs/reference/buildx_history_open.md         | 17 +++++++
 docs/reference/buildx_history_rm.md           | 25 +++++++++++
 docs/reference/buildx_history_trace.md        | 33 ++++++++++++++
 9 files changed, 237 insertions(+)

diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md
index 34b3bc2c..468cf405 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -15,3 +15,31 @@ Export a build into Docker Desktop bundle
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Export one or more build records to `.dockerbuild` archive files. These archives
+contain metadata, logs, and build outputs, and can be imported into Docker
+Desktop or shared across environments.
+
+## Examples
+
+### Export a single build to a custom file
+
+```console
+docker buildx history export mybuild --output mybuild.dockerbuild
+```
+
+### Export multiple builds to individual `.dockerbuild` files
+
+This example writes `mybuild.dockerbuild` and `backend-build.dockerbuild` to
+the current directory:
+
+```console
+docker buildx history export mybuild backend-build
+```
+
+### Export all build records
+
+```console
+docker buildx history export --all
+```
diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md
index 618a485d..777238c0 100644
--- a/docs/reference/buildx_history_import.md
+++ b/docs/reference/buildx_history_import.md
@@ -14,3 +14,28 @@ Import a build into Docker Desktop
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Import a build record from a `.dockerbuild` archive into Docker Desktop. This
+lets you view, inspect, and analyze builds created in other environments or CI
+pipelines.
+
+## Examples
+
+### Import a `.dockerbuild` archive into Docker Desktop
+
+```console
+docker buildx history import < mybuild.dockerbuild
+```
+
+### Import a file using a specific path
+
+```console
+docker buildx history import --file ./artifacts/backend-build.dockerbuild
+```
+
+### Import a file and open it in Docker Desktop
+
+```console
+docker buildx history import --file ./ci-build.dockerbuild && docker buildx history open ci-build
+```
diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md
index bfad9661..3c47db27 100644
--- a/docs/reference/buildx_history_inspect.md
+++ b/docs/reference/buildx_history_inspect.md
@@ -21,8 +21,20 @@ Inspect a build
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Inspect a build record to view metadata such as duration, status, build inputs,
+platforms, outputs, and attached artifacts. You can also use flags to extract
+provenance, SBOMs, or other detailed information.
+
 ## Examples
 
+### Inspect a build and print metadata
+
+```console
+docker buildx history inspect mybuild
+```
+
 ### <a name="format"></a> Format the output (--format)
 
 The formatting options (`--format`) pretty-prints the output to `pretty` (default),
diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md
index 453e02e2..be8eb920 100644
--- a/docs/reference/buildx_history_inspect_attachment.md
+++ b/docs/reference/buildx_history_inspect_attachment.md
@@ -15,3 +15,24 @@ Inspect a build attachment
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Inspect a specific attachment from a build record, such as a provenance file or
+SBOM. Attachments are optional artifacts stored with the build and may be
+platform-specific.
+
+## Examples
+
+### Inspect a provenance attachment from a build
+
+```console
+docker buildx history inspect attachment mybuild --type https://slsa.dev/provenance/v0.2
+```
+
+### Inspect a SBOM for linux/amd64
+
+```console
+docker buildx history inspect attachment mybuild \
+  --type application/vnd.cyclonedx+json \
+  --platform linux/amd64
+```
diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md
index 5418ce39..687aaece 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -14,3 +14,34 @@ Print the logs of a build
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Print the logs for a completed build. The output appears in the same format as `--progress=plain`, showing the full logs for each step without multiplexing.
+
+By default, this shows logs for the most recent build on the current builder.
+
+## Examples
+
+### Print logs for the most recent build
+
+```console
+docker buildx history logs
+```
+
+### Print logs for a specific build
+
+```console
+docker buildx history logs mybuild
+```
+
+### Print logs in JSON format
+
+```console
+docker buildx history logs mybuild --progress rawjson
+```
+
+### Print logs in TTY format
+
+```console
+docker buildx history logs mybuild --progress tty
+```
diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md
index e63224b1..85f88225 100644
--- a/docs/reference/buildx_history_ls.md
+++ b/docs/reference/buildx_history_ls.md
@@ -17,3 +17,48 @@ List build records
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+List completed builds recorded by the active builder. Each entry includes the
+build ID, name (if available), status, timestamp, and duration.
+
+By default, only records for the current builder are shown. You can filter
+results using flags.
+
+## Examples
+
+### List all build records for the current builder
+
+```console
+docker buildx history ls
+```
+
+### List only failed builds
+
+```console
+docker buildx history ls --filter status=error
+```
+
+### List builds from the current directory
+
+```console
+docker buildx history ls --local
+```
+
+### Display full output without truncation
+
+```console
+docker buildx history ls --no-trunc
+```
+
+### Format output as JSON
+
+```console
+docker buildx history ls --format json
+```
+
+### Use a Go template to print name and durations
+
+```console
+docker buildx history ls --format '{{.Name}} - {{.Duration}}'
+```
diff --git a/docs/reference/buildx_history_open.md b/docs/reference/buildx_history_open.md
index 50ed35ff..f0c19cc6 100644
--- a/docs/reference/buildx_history_open.md
+++ b/docs/reference/buildx_history_open.md
@@ -13,3 +13,20 @@ Open a build in Docker Desktop
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Open a build record in Docker Desktop for visual inspection. This requires Docker Desktop to be installed and running on the host machine.
+
+## Examples
+
+### Open the most recent build in Docker Desktop
+
+```console
+docker buildx history open
+```
+
+### Open a specific build by name
+
+```console
+docker buildx history open mybuild
+```
diff --git a/docs/reference/buildx_history_rm.md b/docs/reference/buildx_history_rm.md
index 34bbf14d..75687340 100644
--- a/docs/reference/buildx_history_rm.md
+++ b/docs/reference/buildx_history_rm.md
@@ -14,3 +14,28 @@ Remove build records
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+Remove one or more build records from the current builder’s history. You can
+remove specific builds by name or ID, or delete all records at once using
+the `--all` flag.
+
+## Examples
+
+### Remove a specific build
+
+```console
+docker buildx history rm mybuild
+```
+
+### Remove multiple builds
+
+```console
+docker buildx history rm mybuild frontend-build backend-build
+```
+
+### Remove all build records from the current builder
+
+```console
+docker buildx history rm --all
+```
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index 54362b1a..35bbf2e0 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -15,3 +15,36 @@ Show the OpenTelemetry trace of a build record
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+View the OpenTelemetry trace for a completed build. This command loads the
+trace into a Jaeger UI running in a local container
+(or a custom instance if configured) and opens it in your browser.
+
+This helps analyze build performance, step timing, and internal execution flows.
+
+## Examples
+
+### Open the OpenTelemetry trace for the most recent build
+
+```console
+docker buildx history trace
+```
+
+### Open the trace for a specific build
+
+```console
+docker buildx history trace mybuild
+```
+
+### Run the Jaeger UI on a specific port
+
+```console
+docker buildx history trace mybuild --addr 127.0.0.1:16686
+```
+
+### Compare two build traces
+
+```console
+docker buildx history trace --compare mybuild:main mybuild:feature
+```

From 23ce21c341d5466e148dda953b0f9d08e1d8f187 Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Tue, 22 Apr 2025 12:14:51 -0400
Subject: [PATCH 2/5] feedback + updated examples + added links for h3 headings

Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>
---
 docs/reference/buildx_history.md              | 29 ++++++++++
 docs/reference/buildx_history_export.md       | 44 ++++++++++++---
 docs/reference/buildx_history_import.md       | 14 +++--
 docs/reference/buildx_history_inspect.md      | 43 +++++++++++++-
 .../buildx_history_inspect_attachment.md      | 54 ++++++++++++++++--
 docs/reference/buildx_history_logs.md         | 46 ++++++++++++---
 docs/reference/buildx_history_ls.md           | 56 +++++++++++++++----
 docs/reference/buildx_history_open.md         | 15 +++--
 docs/reference/buildx_history_rm.md           | 20 +++++--
 docs/reference/buildx_history_trace.md        | 37 +++++++++---
 10 files changed, 300 insertions(+), 58 deletions(-)

diff --git a/docs/reference/buildx_history.md b/docs/reference/buildx_history.md
index 7eaa7c84..ef0cf8b1 100644
--- a/docs/reference/buildx_history.md
+++ b/docs/reference/buildx_history.md
@@ -27,3 +27,32 @@ Commands to work on build records
 
 <!---MARKER_GEN_END-->
 
+### Build references
+
+Most `buildx history` subcommands accept a build reference to identify which
+build to act on. You can specify the build in two ways:
+
+- By build ID, fetched by `docker buildx history ls`:
+
+    ```console
+    docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output build.dockerbuild
+    ```
+
+- By relative offset, to refer to recent builds:
+
+    ```console
+    docker buildx history export ^1 --output build.dockerbuild
+    ```
+
+    - `^0` or no reference targets the most recent build
+    - `^1` refers to the build before the most recent
+    - `^2` refers to two builds back, and so on
+
+Offset references are supported in the following `buildx history` commands:
+
+- `logs`
+- `inspect`
+- `open`
+- `trace`
+- `export`
+- `rm`
diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md
index 468cf405..c24ab53c 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -23,23 +23,49 @@ Desktop or shared across environments.
 
 ## Examples
 
-### Export a single build to a custom file
+### <a name="export-single-build"></a> Export a single build to a custom file
 
 ```console
-docker buildx history export mybuild --output mybuild.dockerbuild
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
 ```
 
-### Export multiple builds to individual `.dockerbuild` files
-
-This example writes `mybuild.dockerbuild` and `backend-build.dockerbuild` to
-the current directory:
+You can find build IDs by running:
 
 ```console
-docker buildx history export mybuild backend-build
+docker buildx history ls
 ```
 
-### Export all build records
+### <a name="export-multiple-builds"></a> Export multiple builds to individual `.dockerbuild` files
+
+To export two builds to separate files:
 
 ```console
-docker buildx history export --all
+# Using build IDs
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt -o mybuild.dockerbuild
+docker buildx history export qsiifiuf1ad9pa9qvppc0z1l3 -o backend-build.dockerbuild
+
+# Or using relative offsets
+docker buildx history export ^1 -o mybuild.dockerbuild
+docker buildx history export ^2 -o backend-build.dockerbuild
+```
+
+Or use shell redirection:
+
+```console
+docker buildx history export ^1 > mybuild.dockerbuild
+docker buildx history export ^2 > backend-build.dockerbuild
+```
+
+### <a name="export-all-builds"></a> Export all build records to a file
+
+Use the `--all` flag and redirect the output:
+
+```console
+docker buildx history export --all > all-builds.dockerbuild
+```
+
+Or use the `--output` flag:
+
+```console
+docker buildx history export --all -o all-builds.dockerbuild
 ```
diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md
index 777238c0..e890b7c1 100644
--- a/docs/reference/buildx_history_import.md
+++ b/docs/reference/buildx_history_import.md
@@ -22,20 +22,26 @@ pipelines.
 
 ## Examples
 
-### Import a `.dockerbuild` archive into Docker Desktop
+### <a name="import-dockerbuild"></a> Import a `.dockerbuild` archive from standard input
 
 ```console
 docker buildx history import < mybuild.dockerbuild
 ```
 
-### Import a file using a specific path
+### <a name="import-build-archive"></a> Import a build archive from a file
 
 ```console
 docker buildx history import --file ./artifacts/backend-build.dockerbuild
 ```
 
-### Import a file and open it in Docker Desktop
+### <a name="open-build-manually"></a> Open a build manually
+
+By default, the `import` command automatically opens the imported build in Docker
+Desktop. You don't need to run `open` unless you're opening a specific build
+or re-opening it later.
+
+If you've imported multiple builds, you can open one manually:
 
 ```console
-docker buildx history import --file ./ci-build.dockerbuild && docker buildx history open ci-build
+docker buildx history open ci-build
 ```
diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md
index 3c47db27..9246fbdd 100644
--- a/docs/reference/buildx_history_inspect.md
+++ b/docs/reference/buildx_history_inspect.md
@@ -29,10 +29,44 @@ provenance, SBOMs, or other detailed information.
 
 ## Examples
 
-### Inspect a build and print metadata
+### <a name="inspect-most-recent-build"></a> Inspect the most recent build
 
 ```console
-docker buildx history inspect mybuild
+$ docker buildx history inspect
+Name:           buildx (binaries)
+Context:        .
+Dockerfile:     Dockerfile
+VCS Repository: https://github.com/crazy-max/buildx.git
+VCS Revision:   f15eaa1ee324ffbbab29605600d27a84cab86361
+Target:         binaries
+Platforms:      linux/amd64
+Keep Git Dir:   true
+
+Started:        2025-02-07 11:56:24
+Duration:       1m  1s
+Build Steps:    16/16 (25% cached)
+
+Image Resolve Mode:     local
+
+Materials:
+URI                                                             DIGEST
+pkg:docker/docker/dockerfile@1                                  sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25
+pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64        sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
+pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64           sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3
+
+Attachments:
+DIGEST                                                                  PLATFORM        TYPE
+sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3                 https://slsa.dev/provenance/v0.2
+```
+
+### <a name="inspect-specific-build"></a> Inspect a specific build
+
+```console
+# Using a build ID
+docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history inspect ^1
 ```
 
 ### <a name="format"></a> Format the output (--format)
@@ -40,6 +74,8 @@ docker buildx history inspect mybuild
 The formatting options (`--format`) pretty-prints the output to `pretty` (default),
 `json` or using a Go template.
 
+**Pretty output**
+
 ```console
 $ docker buildx history inspect
 Name:           buildx (binaries)
@@ -69,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3
 
 Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
 ```
+**JSON output**
 
 ```console
 $ docker buildx history inspect --format json
@@ -123,6 +160,8 @@ $ docker buildx history inspect --format json
 }
 ```
 
+**Go template output**
+
 ```console
 $ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})"
 buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361)
diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md
index be8eb920..9377b865 100644
--- a/docs/reference/buildx_history_inspect_attachment.md
+++ b/docs/reference/buildx_history_inspect_attachment.md
@@ -23,16 +23,60 @@ platform-specific.
 
 ## Examples
 
-### Inspect a provenance attachment from a build
+### <a name="inspect-provenance-attachment"></a> Inspect a provenance attachment from a build
+
+Supported types include `provenance` and `sbom`.
 
 ```console
-docker buildx history inspect attachment mybuild --type https://slsa.dev/provenance/v0.2
+$ docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt --type provenance
+{
+  "_type": "https://slsa.dev/provenance/v0.2",
+  "buildDefinition": {
+    "buildType": "https://build.docker.com/BuildKit@v1",
+    "externalParameters": {
+      "target": "app",
+      "platforms": ["linux/amd64"]
+    }
+  },
+  "runDetails": {
+    "builder": "docker",
+    "by": "ci@docker.com"
+  }
+}
 ```
 
-### Inspect a SBOM for linux/amd64
+### <a name="insepct-SBOM"></a> Inspect a SBOM for linux/amd64
 
 ```console
-docker buildx history inspect attachment mybuild \
-  --type application/vnd.cyclonedx+json \
+$ docker buildx history inspect attachment ^0 \
+  --type sbom \
   --platform linux/amd64
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "components": [
+    {
+      "type": "library",
+      "name": "alpine",
+      "version": "3.18.2"
+    }
+  ]
+}
 ```
+
+### <a name="inspect-attachment-digest"></a> Inspect an attachment by digest
+
+You can inspect an attachment directly using its digset, which you can get from
+the `inspect` output:
+
+```console
+# Using a build ID
+docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt sha256:abcdef123456...
+
+# Or using a relative offset
+docker buildx history inspect attachment ^0 sha256:abcdef123456...
+```
+
+Use `--type sbom` or `--type provenance` to filter attachments by type. To
+inspect a specific attachment by digest, omit the `--type` flag.
diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md
index 687aaece..9b917d66 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -16,32 +16,60 @@ Print the logs of a build
 
 ## Description
 
-Print the logs for a completed build. The output appears in the same format as `--progress=plain`, showing the full logs for each step without multiplexing.
+Print the logs for a completed build. The output appears in the same format as
+`--progress=plain`, showing the full logs for each step.
 
 By default, this shows logs for the most recent build on the current builder.
 
+You can also specify an earlier build using an offset. For example:
+
+- `^1` shows logs for the build before the most recent
+- `^2` shows logs for the build two steps back
+
 ## Examples
 
-### Print logs for the most recent build
+### <a name="print-logs-recent-build"></a> Print logs for the most recent build
 
 ```console
-docker buildx history logs
+$ docker buildx history logs
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 31B done
+#1 DONE 0.0s
+#2 [internal] load .dockerignore
+#2 transferring context: 2B done
+#2 DONE 0.0s
+...
 ```
 
-### Print logs for a specific build
+By default, this shows logs for the most recent build on the current builder.
+
+### <a name="print-logs-specific-build"></a> Print logs for a specific build
+
+To print logs for a specific build, use a build ID or offset:
 
 ```console
-docker buildx history logs mybuild
+# Using a build ID
+docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history logs ^1
 ```
 
-### Print logs in JSON format
+### <a name="print-logs-json"></a> Print logs in JSON format
 
 ```console
-docker buildx history logs mybuild --progress rawjson
+$ docker buildx history logs ^1 --progress rawjson
+{"id":"buildx_step_1","status":"START","timestamp":"2024-05-01T12:34:56.789Z","detail":"[internal] load build definition from Dockerfile"}
+{"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000}
+...
 ```
 
-### Print logs in TTY format
+### <a name="print-logs-tty"></a> Print logs in TTY format
 
 ```console
-docker buildx history logs mybuild --progress tty
+# Using a build ID
+docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt --progress tty
+
+# Or using a relative offset
+docker buildx history logs ^1 --progress tty
 ```
diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md
index 85f88225..9277cab5 100644
--- a/docs/reference/buildx_history_ls.md
+++ b/docs/reference/buildx_history_ls.md
@@ -20,45 +20,81 @@ List build records
 ## Description
 
 List completed builds recorded by the active builder. Each entry includes the
-build ID, name (if available), status, timestamp, and duration.
+build ID, name, status, timestamp, and duration.
 
 By default, only records for the current builder are shown. You can filter
 results using flags.
 
 ## Examples
 
-### List all build records for the current builder
+### <a name="list-build-records-current"></a> List all build records for the current builder
 
 ```console
-docker buildx history ls
+$ docker buildx history ls
+BUILD ID                    NAME           STATUS     CREATED AT        DURATION
+qu2gsuo8ejqrwdfii23xkkckt   .dev/2850      Completed  3 days ago        1.4s
+qsiifiuf1ad9pa9qvppc0z1l3   .dev/2850      Completed  3 days ago        1.3s
+g9808bwrjrlkbhdamxklx660b   .dev/3120      Completed  5 days ago        2.1s
 ```
 
-### List only failed builds
+### <a name="list-failed-builds"></a> List only failed builds
 
 ```console
 docker buildx history ls --filter status=error
 ```
 
-### List builds from the current directory
+You can filter the list using the `--filter` flag. Supported filters include:
+
+| Filter | Supported comparisons | Example |
+|:-------|:----------------------|:--------|
+| `ref`, `repository`, `status` | Support `=` and `!=` comparisons | `--filter status!=success` |
+| `startedAt`, `completedAt`, `duration` | Support `<` and `>` comparisons with time values | `--filter duration>30s` |
+
+You can combine multiple filters by repeating the `--filter` flag:
+
+```console
+docker buildx history ls --filter status=error --filter duration>30s
+```
+
+### <a name="list-builds-current-project"></a> List builds from the current project
 
 ```console
 docker buildx history ls --local
 ```
 
-### Display full output without truncation
+### <a name="display-full-output"></a> Display full output without truncation
 
 ```console
 docker buildx history ls --no-trunc
 ```
 
-### Format output as JSON
+### <a name="list-as-json"></a> Format output as JSON
 
 ```console
-docker buildx history ls --format json
+$ docker buildx history ls --format json
+[
+  {
+    "ID": "qu2gsuo8ejqrwdfii23xkkckt",
+    "Name": ".dev/2850",
+    "Status": "Completed",
+    "CreatedAt": "2025-04-15T12:33:00Z",
+    "Duration": "1.4s"
+  },
+  {
+    "ID": "qsiifiuf1ad9pa9qvppc0z1l3",
+    "Name": ".dev/2850",
+    "Status": "Completed",
+    "CreatedAt": "2025-04-15T12:29:00Z",
+    "Duration": "1.3s"
+  }
+]
 ```
 
-### Use a Go template to print name and durations
+### <a name="list-go-template"></a> Use a Go template to print name and durations
 
 ```console
-docker buildx history ls --format '{{.Name}} - {{.Duration}}'
+$ docker buildx history ls --format '{{.Name}} - {{.Duration}}'
+.dev/2850 - 1.4s
+.dev/2850 - 1.3s
+.dev/3120 - 2.1s
 ```
diff --git a/docs/reference/buildx_history_open.md b/docs/reference/buildx_history_open.md
index f0c19cc6..b9ed6f81 100644
--- a/docs/reference/buildx_history_open.md
+++ b/docs/reference/buildx_history_open.md
@@ -15,18 +15,25 @@ Open a build in Docker Desktop
 
 ## Description
 
-Open a build record in Docker Desktop for visual inspection. This requires Docker Desktop to be installed and running on the host machine.
+Open a build record in Docker Desktop for visual inspection. This requires
+Docker Desktop to be installed and running on the host machine.
 
 ## Examples
 
-### Open the most recent build in Docker Desktop
+### <a name="open-most-recent-build"></a> Open the most recent build in Docker Desktop
 
 ```console
 docker buildx history open
 ```
 
-### Open a specific build by name
+By default, this opens the most recent build on the current builder.
+
+### <a name="open-specific-build"></a> Open a specific build
 
 ```console
-docker buildx history open mybuild
+# Using a build ID
+docker buildx history open qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history open ^1
 ```
diff --git a/docs/reference/buildx_history_rm.md b/docs/reference/buildx_history_rm.md
index 75687340..e7bbd1d8 100644
--- a/docs/reference/buildx_history_rm.md
+++ b/docs/reference/buildx_history_rm.md
@@ -17,24 +17,32 @@ Remove build records
 ## Description
 
 Remove one or more build records from the current builder’s history. You can
-remove specific builds by name or ID, or delete all records at once using
+remove specific builds by ID or offset, or delete all records at once using
 the `--all` flag.
 
 ## Examples
 
-### Remove a specific build
+### <a name="remove-specific-build"></a> Remove a specific build
 
 ```console
-docker buildx history rm mybuild
+# Using a build ID
+docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history rm ^1
 ```
 
-### Remove multiple builds
+### <a name="remove-multiple-builds"></a> Remove multiple builds
 
 ```console
-docker buildx history rm mybuild frontend-build backend-build
+# Using build IDs
+docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
+
+# Or using relative offsets
+docker buildx history rm ^1 ^2
 ```
 
-### Remove all build records from the current builder
+### <a name="remove-all-build-records"></a> Remove all build records from the current builder
 
 ```console
 docker buildx history rm --all
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index 35bbf2e0..b95553d1 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -18,33 +18,52 @@ Show the OpenTelemetry trace of a build record
 ## Description
 
 View the OpenTelemetry trace for a completed build. This command loads the
-trace into a Jaeger UI running in a local container
-(or a custom instance if configured) and opens it in your browser.
+trace into a Jaeger UI viewer and opens it in your browser.
 
 This helps analyze build performance, step timing, and internal execution flows.
 
 ## Examples
 
-### Open the OpenTelemetry trace for the most recent build
+### <a name="open-opentelemetry-trace"></a> Open the OpenTelemetry trace for the most recent build
+
+This command starts a temporary Jaeger UI server and opens your default browser
+to view the trace.
 
 ```console
 docker buildx history trace
 ```
 
-### Open the trace for a specific build
+### <a name="open-trace-specific-build"></a> Open the trace for a specific build
 
 ```console
-docker buildx history trace mybuild
+# Using a build ID
+docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history trace ^1
 ```
 
-### Run the Jaeger UI on a specific port
+### <a name="run-Jaegar-UI-port"></a> Run the Jaeger UI on a specific port
 
 ```console
-docker buildx history trace mybuild --addr 127.0.0.1:16686
+# Using a build ID
+docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt --addr 127.0.0.1:16686
+
+# Or using a relative offset
+docker buildx history trace ^1 --addr 127.0.0.1:16686
 ```
 
-### Compare two build traces
+### <a name="compare-traces"></a> Compare two build traces
+
+Compare two specific builds by name:
 
 ```console
-docker buildx history trace --compare mybuild:main mybuild:feature
+# Using build IDs
+docker buildx history trace --compare qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
+
+# Or using a single relative offset
+docker buildx history trace --compare ^1
 ```
+
+When you use a single reference with `--compare`, it compares that build
+against the most recent one.

From 03019049e8a48fdf832da5bf19acdbb48b941de6 Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Wed, 23 Apr 2025 09:54:18 -0400
Subject: [PATCH 3/5] addressed feedback

Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>
---
 docs/reference/buildx_history_export.md |  6 ++----
 docs/reference/buildx_history_logs.md   | 10 ----------
 docs/reference/buildx_history_trace.md  |  4 ++--
 3 files changed, 4 insertions(+), 16 deletions(-)

diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md
index c24ab53c..de9c750e 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -41,12 +41,10 @@ To export two builds to separate files:
 
 ```console
 # Using build IDs
-docker buildx history export qu2gsuo8ejqrwdfii23xkkckt -o mybuild.dockerbuild
-docker buildx history export qsiifiuf1ad9pa9qvppc0z1l3 -o backend-build.dockerbuild
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
 
 # Or using relative offsets
-docker buildx history export ^1 -o mybuild.dockerbuild
-docker buildx history export ^2 -o backend-build.dockerbuild
+docker buildx history export ^1 ^2 -o multi.dockerbuild
 ```
 
 Or use shell redirection:
diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md
index 9b917d66..6785b719 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -63,13 +63,3 @@ $ docker buildx history logs ^1 --progress rawjson
 {"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000}
 ...
 ```
-
-### <a name="print-logs-tty"></a> Print logs in TTY format
-
-```console
-# Using a build ID
-docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt --progress tty
-
-# Or using a relative offset
-docker buildx history logs ^1 --progress tty
-```
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index b95553d1..f9b45e21 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -59,10 +59,10 @@ Compare two specific builds by name:
 
 ```console
 # Using build IDs
-docker buildx history trace --compare qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
+docker buildx history trace --compare=qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
 
 # Or using a single relative offset
-docker buildx history trace --compare ^1
+docker buildx history trace --compare=^1
 ```
 
 When you use a single reference with `--compare`, it compares that build

From 6ed39b2618c68c52c295b9d4a9048d0b472c03e6 Mon Sep 17 00:00:00 2001
From: sarahsanders-docker <sarah.sanders@docker.com>
Date: Fri, 25 Apr 2025 09:57:25 -0400
Subject: [PATCH 4/5] fix examples and headings

Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>
---
 docs/reference/buildx_history_export.md       | 24 ++++++++++++++-----
 docs/reference/buildx_history_import.md       |  8 +++----
 docs/reference/buildx_history_inspect.md      |  4 ++--
 .../buildx_history_inspect_attachment.md      |  8 +++----
 docs/reference/buildx_history_logs.md         |  8 +++----
 docs/reference/buildx_history_ls.md           | 22 +++++++++--------
 docs/reference/buildx_history_open.md         |  4 ++--
 docs/reference/buildx_history_rm.md           |  6 ++---
 docs/reference/buildx_history_trace.md        | 12 +++++-----
 9 files changed, 55 insertions(+), 41 deletions(-)

diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md
index de9c750e..1b223798 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -7,10 +7,10 @@ Export a build into Docker Desktop bundle
 
 | Name             | Type     | Default | Description                              |
 |:-----------------|:---------|:--------|:-----------------------------------------|
-| `--all`          | `bool`   |         | Export all records for the builder       |
-| `--builder`      | `string` |         | Override the configured builder instance |
+| [`--all`](#all)          | `bool`   |         | Export all records for the builder       |
+| [`--builder`](#builder)      | `string` |         | Override the configured builder instance |
 | `-D`, `--debug`  | `bool`   |         | Enable debug logging                     |
-| `-o`, `--output` | `string` |         | Output file path                         |
+| [`-o`](#o), [`--output`](#output) | `string` |         | Output file path                         |
 
 
 <!---MARKER_GEN_END-->
@@ -23,7 +23,7 @@ Desktop or shared across environments.
 
 ## Examples
 
-### <a name="export-single-build"></a> Export a single build to a custom file
+### <a name="output"></a> Export a single build to a custom file (--output)
 
 ```console
 docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
@@ -35,7 +35,7 @@ You can find build IDs by running:
 docker buildx history ls
 ```
 
-### <a name="export-multiple-builds"></a> Export multiple builds to individual `.dockerbuild` files
+### <a name="o"></a> Export multiple builds to individual `.dockerbuild` files (-o)
 
 To export two builds to separate files:
 
@@ -54,7 +54,7 @@ docker buildx history export ^1 > mybuild.dockerbuild
 docker buildx history export ^2 > backend-build.dockerbuild
 ```
 
-### <a name="export-all-builds"></a> Export all build records to a file
+### <a name="all"></a> Export all build records to a file (--all)
 
 Use the `--all` flag and redirect the output:
 
@@ -67,3 +67,15 @@ Or use the `--output` flag:
 ```console
 docker buildx history export --all -o all-builds.dockerbuild
 ```
+
+### <a name="builder"></a> Use a specific builder instance (--builder)
+
+```console
+docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
+```
+
+### <a name="debug"></a> Enable debug logging (--debug)
+
+```console
+docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
+```
\ No newline at end of file
diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md
index e890b7c1..e269d6ad 100644
--- a/docs/reference/buildx_history_import.md
+++ b/docs/reference/buildx_history_import.md
@@ -9,7 +9,7 @@ Import a build into Docker Desktop
 |:----------------|:--------------|:--------|:-----------------------------------------|
 | `--builder`     | `string`      |         | Override the configured builder instance |
 | `-D`, `--debug` | `bool`        |         | Enable debug logging                     |
-| `-f`, `--file`  | `stringArray` |         | Import from a file path                  |
+| [`-f`](#file), [`--file`](#file)  | `stringArray` |         | Import from a file path                  |
 
 
 <!---MARKER_GEN_END-->
@@ -22,19 +22,19 @@ pipelines.
 
 ## Examples
 
-### <a name="import-dockerbuild"></a> Import a `.dockerbuild` archive from standard input
+### Import a `.dockerbuild` archive from standard input
 
 ```console
 docker buildx history import < mybuild.dockerbuild
 ```
 
-### <a name="import-build-archive"></a> Import a build archive from a file
+### <a name="file"></a> Import a build archive from a file (--file)
 
 ```console
 docker buildx history import --file ./artifacts/backend-build.dockerbuild
 ```
 
-### <a name="open-build-manually"></a> Open a build manually
+### Open a build manually
 
 By default, the `import` command automatically opens the imported build in Docker
 Desktop. You don't need to run `open` unless you're opening a specific build
diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md
index 9246fbdd..942e1a3f 100644
--- a/docs/reference/buildx_history_inspect.md
+++ b/docs/reference/buildx_history_inspect.md
@@ -29,7 +29,7 @@ provenance, SBOMs, or other detailed information.
 
 ## Examples
 
-### <a name="inspect-most-recent-build"></a> Inspect the most recent build
+### Inspect the most recent build
 
 ```console
 $ docker buildx history inspect
@@ -59,7 +59,7 @@ DIGEST                                                                  PLATFORM
 sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3                 https://slsa.dev/provenance/v0.2
 ```
 
-### <a name="inspect-specific-build"></a> Inspect a specific build
+### Inspect a specific build
 
 ```console
 # Using a build ID
diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md
index 9377b865..d7f10b63 100644
--- a/docs/reference/buildx_history_inspect_attachment.md
+++ b/docs/reference/buildx_history_inspect_attachment.md
@@ -10,7 +10,7 @@ Inspect a build attachment
 | `--builder`     | `string` |         | Override the configured builder instance |
 | `-D`, `--debug` | `bool`   |         | Enable debug logging                     |
 | `--platform`    | `string` |         | Platform of attachment                   |
-| `--type`        | `string` |         | Type of attachment                       |
+| [`--type`](#type)        | `string` |         | Type of attachment                       |
 
 
 <!---MARKER_GEN_END-->
@@ -23,7 +23,7 @@ platform-specific.
 
 ## Examples
 
-### <a name="inspect-provenance-attachment"></a> Inspect a provenance attachment from a build
+### <a name="type"></a> Inspect a provenance attachment from a build (--type)
 
 Supported types include `provenance` and `sbom`.
 
@@ -45,7 +45,7 @@ $ docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt --type prov
 }
 ```
 
-### <a name="insepct-SBOM"></a> Inspect a SBOM for linux/amd64
+### Inspect a SBOM for linux/amd64
 
 ```console
 $ docker buildx history inspect attachment ^0 \
@@ -65,7 +65,7 @@ $ docker buildx history inspect attachment ^0 \
 }
 ```
 
-### <a name="inspect-attachment-digest"></a> Inspect an attachment by digest
+### Inspect an attachment by digest
 
 You can inspect an attachment directly using its digset, which you can get from
 the `inspect` output:
diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md
index 6785b719..61b9aa4d 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -9,7 +9,7 @@ Print the logs of a build
 |:----------------|:---------|:--------|:--------------------------------------------------|
 | `--builder`     | `string` |         | Override the configured builder instance          |
 | `-D`, `--debug` | `bool`   |         | Enable debug logging                              |
-| `--progress`    | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
+| [`--progress`](#progress) | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
 
 
 <!---MARKER_GEN_END-->
@@ -28,7 +28,7 @@ You can also specify an earlier build using an offset. For example:
 
 ## Examples
 
-### <a name="print-logs-recent-build"></a> Print logs for the most recent build
+### Print logs for the most recent build
 
 ```console
 $ docker buildx history logs
@@ -43,7 +43,7 @@ $ docker buildx history logs
 
 By default, this shows logs for the most recent build on the current builder.
 
-### <a name="print-logs-specific-build"></a> Print logs for a specific build
+### Print logs for a specific build
 
 To print logs for a specific build, use a build ID or offset:
 
@@ -55,7 +55,7 @@ docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
 docker buildx history logs ^1
 ```
 
-### <a name="print-logs-json"></a> Print logs in JSON format
+### <a name="progress"></a> Set type of progress output (--progress)
 
 ```console
 $ docker buildx history logs ^1 --progress rawjson
diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md
index 9277cab5..341a45ba 100644
--- a/docs/reference/buildx_history_ls.md
+++ b/docs/reference/buildx_history_ls.md
@@ -9,10 +9,10 @@ List build records
 |:----------------|:--------------|:--------|:---------------------------------------------|
 | `--builder`     | `string`      |         | Override the configured builder instance     |
 | `-D`, `--debug` | `bool`        |         | Enable debug logging                         |
-| `--filter`      | `stringArray` |         | Provide filter values (e.g., `status=error`) |
-| `--format`      | `string`      | `table` | Format the output                            |
-| `--local`       | `bool`        |         | List records for current repository only     |
-| `--no-trunc`    | `bool`        |         | Don't truncate output                        |
+| [`--filter`](#filter)      | `stringArray` |         | Provide filter values (e.g., `status=error`) |
+| [`--format`](#format)      | `string`      | `table` | Format the output                            |
+| [`--local`](#local)       | `bool`        |         | List records for current repository only     |
+| [`--no-trunc`](#no-trunc)    | `bool`        |         | Don't truncate output                        |
 
 
 <!---MARKER_GEN_END-->
@@ -27,7 +27,7 @@ results using flags.
 
 ## Examples
 
-### <a name="list-build-records-current"></a> List all build records for the current builder
+### List all build records for the current builder
 
 ```console
 $ docker buildx history ls
@@ -37,7 +37,7 @@ qsiifiuf1ad9pa9qvppc0z1l3   .dev/2850      Completed  3 days ago        1.3s
 g9808bwrjrlkbhdamxklx660b   .dev/3120      Completed  5 days ago        2.1s
 ```
 
-### <a name="list-failed-builds"></a> List only failed builds
+### <a name="filter"></a> List failed builds (--filter)
 
 ```console
 docker buildx history ls --filter status=error
@@ -56,19 +56,21 @@ You can combine multiple filters by repeating the `--filter` flag:
 docker buildx history ls --filter status=error --filter duration>30s
 ```
 
-### <a name="list-builds-current-project"></a> List builds from the current project
+### <a name="local"></a> List builds from the current project (--local)
 
 ```console
 docker buildx history ls --local
 ```
 
-### <a name="display-full-output"></a> Display full output without truncation
+### <a name="no-trunc"></a> Display full output without truncation (--no-trunc)
 
 ```console
 docker buildx history ls --no-trunc
 ```
 
-### <a name="list-as-json"></a> Format output as JSON
+### <a name="format"></a> Format output (--format)
+
+**JSON output**
 
 ```console
 $ docker buildx history ls --format json
@@ -90,7 +92,7 @@ $ docker buildx history ls --format json
 ]
 ```
 
-### <a name="list-go-template"></a> Use a Go template to print name and durations
+**Go template output**
 
 ```console
 $ docker buildx history ls --format '{{.Name}} - {{.Duration}}'
diff --git a/docs/reference/buildx_history_open.md b/docs/reference/buildx_history_open.md
index b9ed6f81..e0817b41 100644
--- a/docs/reference/buildx_history_open.md
+++ b/docs/reference/buildx_history_open.md
@@ -20,7 +20,7 @@ Docker Desktop to be installed and running on the host machine.
 
 ## Examples
 
-### <a name="open-most-recent-build"></a> Open the most recent build in Docker Desktop
+### Open the most recent build in Docker Desktop
 
 ```console
 docker buildx history open
@@ -28,7 +28,7 @@ docker buildx history open
 
 By default, this opens the most recent build on the current builder.
 
-### <a name="open-specific-build"></a> Open a specific build
+### Open a specific build
 
 ```console
 # Using a build ID
diff --git a/docs/reference/buildx_history_rm.md b/docs/reference/buildx_history_rm.md
index e7bbd1d8..dedf1a0c 100644
--- a/docs/reference/buildx_history_rm.md
+++ b/docs/reference/buildx_history_rm.md
@@ -22,7 +22,7 @@ the `--all` flag.
 
 ## Examples
 
-### <a name="remove-specific-build"></a> Remove a specific build
+### Remove a specific build
 
 ```console
 # Using a build ID
@@ -32,7 +32,7 @@ docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt
 docker buildx history rm ^1
 ```
 
-### <a name="remove-multiple-builds"></a> Remove multiple builds
+### Remove multiple builds
 
 ```console
 # Using build IDs
@@ -42,7 +42,7 @@ docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
 docker buildx history rm ^1 ^2
 ```
 
-### <a name="remove-all-build-records"></a> Remove all build records from the current builder
+### Remove all build records from the current builder
 
 ```console
 docker buildx history rm --all
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index f9b45e21..19912f44 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -7,9 +7,9 @@ Show the OpenTelemetry trace of a build record
 
 | Name            | Type     | Default       | Description                              |
 |:----------------|:---------|:--------------|:-----------------------------------------|
-| `--addr`        | `string` | `127.0.0.1:0` | Address to bind the UI server            |
+| [`--addr`](#addr)        | `string` | `127.0.0.1:0` | Address to bind the UI server            |
 | `--builder`     | `string` |               | Override the configured builder instance |
-| `--compare`     | `string` |               | Compare with another build reference     |
+| [`--compare`](#compare)     | `string` |               | Compare with another build reference     |
 | `-D`, `--debug` | `bool`   |               | Enable debug logging                     |
 
 
@@ -24,7 +24,7 @@ This helps analyze build performance, step timing, and internal execution flows.
 
 ## Examples
 
-### <a name="open-opentelemetry-trace"></a> Open the OpenTelemetry trace for the most recent build
+### Open the OpenTelemetry trace for the most recent build
 
 This command starts a temporary Jaeger UI server and opens your default browser
 to view the trace.
@@ -33,7 +33,7 @@ to view the trace.
 docker buildx history trace
 ```
 
-### <a name="open-trace-specific-build"></a> Open the trace for a specific build
+### Open the trace for a specific build
 
 ```console
 # Using a build ID
@@ -43,7 +43,7 @@ docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt
 docker buildx history trace ^1
 ```
 
-### <a name="run-Jaegar-UI-port"></a> Run the Jaeger UI on a specific port
+### <a name="addr"></a> Run the Jaeger UI on a specific port (--addr)
 
 ```console
 # Using a build ID
@@ -53,7 +53,7 @@ docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt --addr 127.0.0.1:16686
 docker buildx history trace ^1 --addr 127.0.0.1:16686
 ```
 
-### <a name="compare-traces"></a> Compare two build traces
+### <a name="compare"></a> Compare two build traces (--compare)
 
 Compare two specific builds by name:
 

From e1e8f5c68d0360df3d717293ddc54294891e41e7 Mon Sep 17 00:00:00 2001
From: Tonis Tiigi <tonistiigi@gmail.com>
Date: Mon, 5 May 2025 14:31:35 -0700
Subject: [PATCH 5/5] docs: updated reference docs generation

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
---
 docs/reference/buildx_history_export.md            | 12 ++++++------
 docs/reference/buildx_history_import.md            | 10 +++++-----
 .../reference/buildx_history_inspect_attachment.md | 12 ++++++------
 docs/reference/buildx_history_logs.md              |  8 ++++----
 docs/reference/buildx_history_ls.md                | 14 +++++++-------
 docs/reference/buildx_history_trace.md             | 12 ++++++------
 6 files changed, 34 insertions(+), 34 deletions(-)

diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md
index 1b223798..ab8a1ff8 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -5,12 +5,12 @@ Export a build into Docker Desktop bundle
 
 ### Options
 
-| Name             | Type     | Default | Description                              |
-|:-----------------|:---------|:--------|:-----------------------------------------|
-| [`--all`](#all)          | `bool`   |         | Export all records for the builder       |
-| [`--builder`](#builder)      | `string` |         | Override the configured builder instance |
-| `-D`, `--debug`  | `bool`   |         | Enable debug logging                     |
-| [`-o`](#o), [`--output`](#output) | `string` |         | Output file path                         |
+| Name                                   | Type     | Default | Description                              |
+|:---------------------------------------|:---------|:--------|:-----------------------------------------|
+| [`--all`](#all)                        | `bool`   |         | Export all records for the builder       |
+| [`--builder`](#builder)                | `string` |         | Override the configured builder instance |
+| [`-D`](#debug), [`--debug`](#debug)    | `bool`   |         | Enable debug logging                     |
+| [`-o`](#output), [`--output`](#output) | `string` |         | Output file path                         |
 
 
 <!---MARKER_GEN_END-->
diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md
index e269d6ad..cc145ea0 100644
--- a/docs/reference/buildx_history_import.md
+++ b/docs/reference/buildx_history_import.md
@@ -5,11 +5,11 @@ Import a build into Docker Desktop
 
 ### Options
 
-| Name            | Type          | Default | Description                              |
-|:----------------|:--------------|:--------|:-----------------------------------------|
-| `--builder`     | `string`      |         | Override the configured builder instance |
-| `-D`, `--debug` | `bool`        |         | Enable debug logging                     |
-| [`-f`](#file), [`--file`](#file)  | `stringArray` |         | Import from a file path                  |
+| Name                             | Type          | Default | Description                              |
+|:---------------------------------|:--------------|:--------|:-----------------------------------------|
+| `--builder`                      | `string`      |         | Override the configured builder instance |
+| `-D`, `--debug`                  | `bool`        |         | Enable debug logging                     |
+| [`-f`](#file), [`--file`](#file) | `stringArray` |         | Import from a file path                  |
 
 
 <!---MARKER_GEN_END-->
diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md
index d7f10b63..6014e924 100644
--- a/docs/reference/buildx_history_inspect_attachment.md
+++ b/docs/reference/buildx_history_inspect_attachment.md
@@ -5,12 +5,12 @@ Inspect a build attachment
 
 ### Options
 
-| Name            | Type     | Default | Description                              |
-|:----------------|:---------|:--------|:-----------------------------------------|
-| `--builder`     | `string` |         | Override the configured builder instance |
-| `-D`, `--debug` | `bool`   |         | Enable debug logging                     |
-| `--platform`    | `string` |         | Platform of attachment                   |
-| [`--type`](#type)        | `string` |         | Type of attachment                       |
+| Name              | Type     | Default | Description                              |
+|:------------------|:---------|:--------|:-----------------------------------------|
+| `--builder`       | `string` |         | Override the configured builder instance |
+| `-D`, `--debug`   | `bool`   |         | Enable debug logging                     |
+| `--platform`      | `string` |         | Platform of attachment                   |
+| [`--type`](#type) | `string` |         | Type of attachment                       |
 
 
 <!---MARKER_GEN_END-->
diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md
index 61b9aa4d..212b43cc 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -5,10 +5,10 @@ Print the logs of a build
 
 ### Options
 
-| Name            | Type     | Default | Description                                       |
-|:----------------|:---------|:--------|:--------------------------------------------------|
-| `--builder`     | `string` |         | Override the configured builder instance          |
-| `-D`, `--debug` | `bool`   |         | Enable debug logging                              |
+| Name                      | Type     | Default | Description                                       |
+|:--------------------------|:---------|:--------|:--------------------------------------------------|
+| `--builder`               | `string` |         | Override the configured builder instance          |
+| `-D`, `--debug`           | `bool`   |         | Enable debug logging                              |
 | [`--progress`](#progress) | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
 
 
diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md
index 341a45ba..88a7ce34 100644
--- a/docs/reference/buildx_history_ls.md
+++ b/docs/reference/buildx_history_ls.md
@@ -5,14 +5,14 @@ List build records
 
 ### Options
 
-| Name            | Type          | Default | Description                                  |
-|:----------------|:--------------|:--------|:---------------------------------------------|
-| `--builder`     | `string`      |         | Override the configured builder instance     |
-| `-D`, `--debug` | `bool`        |         | Enable debug logging                         |
-| [`--filter`](#filter)      | `stringArray` |         | Provide filter values (e.g., `status=error`) |
-| [`--format`](#format)      | `string`      | `table` | Format the output                            |
+| Name                      | Type          | Default | Description                                  |
+|:--------------------------|:--------------|:--------|:---------------------------------------------|
+| `--builder`               | `string`      |         | Override the configured builder instance     |
+| `-D`, `--debug`           | `bool`        |         | Enable debug logging                         |
+| [`--filter`](#filter)     | `stringArray` |         | Provide filter values (e.g., `status=error`) |
+| [`--format`](#format)     | `string`      | `table` | Format the output                            |
 | [`--local`](#local)       | `bool`        |         | List records for current repository only     |
-| [`--no-trunc`](#no-trunc)    | `bool`        |         | Don't truncate output                        |
+| [`--no-trunc`](#no-trunc) | `bool`        |         | Don't truncate output                        |
 
 
 <!---MARKER_GEN_END-->
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index 19912f44..2b448145 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -5,12 +5,12 @@ Show the OpenTelemetry trace of a build record
 
 ### Options
 
-| Name            | Type     | Default       | Description                              |
-|:----------------|:---------|:--------------|:-----------------------------------------|
-| [`--addr`](#addr)        | `string` | `127.0.0.1:0` | Address to bind the UI server            |
-| `--builder`     | `string` |               | Override the configured builder instance |
-| [`--compare`](#compare)     | `string` |               | Compare with another build reference     |
-| `-D`, `--debug` | `bool`   |               | Enable debug logging                     |
+| Name                    | Type     | Default       | Description                              |
+|:------------------------|:---------|:--------------|:-----------------------------------------|
+| [`--addr`](#addr)       | `string` | `127.0.0.1:0` | Address to bind the UI server            |
+| `--builder`             | `string` |               | Override the configured builder instance |
+| [`--compare`](#compare) | `string` |               | Compare with another build reference     |
+| `-D`, `--debug`         | `bool`   |               | Enable debug logging                     |
 
 
 <!---MARKER_GEN_END-->