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
+### 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 34b3bc2c..ab8a1ff8 100644
--- a/docs/reference/buildx_history_export.md
+++ b/docs/reference/buildx_history_export.md
@@ -5,13 +5,77 @@ Export a build into Docker Desktop bundle
### Options
-| Name | Type | Default | Description |
-|:-----------------|:---------|:--------|:-----------------------------------------|
-| `--all` | `bool` | | Export all records for the builder |
-| `--builder` | `string` | | Override the configured builder instance |
-| `-D`, `--debug` | `bool` | | Enable debug logging |
-| `-o`, `--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 |
+## 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 (--output)
+
+```console
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
+```
+
+You can find build IDs by running:
+
+```console
+docker buildx history ls
+```
+
+### Export multiple builds to individual `.dockerbuild` files (-o)
+
+To export two builds to separate files:
+
+```console
+# Using build IDs
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
+
+# Or using relative offsets
+docker buildx history export ^1 ^2 -o multi.dockerbuild
+```
+
+Or use shell redirection:
+
+```console
+docker buildx history export ^1 > mybuild.dockerbuild
+docker buildx history export ^2 > backend-build.dockerbuild
+```
+
+### Export all build records to a file (--all)
+
+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
+```
+
+### Use a specific builder instance (--builder)
+
+```console
+docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
+```
+
+### 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 618a485d..cc145ea0 100644
--- a/docs/reference/buildx_history_import.md
+++ b/docs/reference/buildx_history_import.md
@@ -5,12 +5,43 @@ 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` | `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 |
+## 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 from standard input
+
+```console
+docker buildx history import < mybuild.dockerbuild
+```
+
+### Import a build archive from a file (--file)
+
+```console
+docker buildx history import --file ./artifacts/backend-build.dockerbuild
+```
+
+### 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 open ci-build
+```
diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md
index bfad9661..942e1a3f 100644
--- a/docs/reference/buildx_history_inspect.md
+++ b/docs/reference/buildx_history_inspect.md
@@ -21,13 +21,61 @@ Inspect a build
+## 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 the most recent build
+
+```console
+$ 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
+```
+
+### Inspect a specific build
+
+```console
+# Using a build ID
+docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history inspect ^1
+```
+
### Format the output (--format)
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)
@@ -57,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3
Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
```
+**JSON output**
```console
$ docker buildx history inspect --format json
@@ -111,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 453e02e2..6014e924 100644
--- a/docs/reference/buildx_history_inspect_attachment.md
+++ b/docs/reference/buildx_history_inspect_attachment.md
@@ -5,13 +5,78 @@ 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` | `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 |
+## 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 (--type)
+
+Supported types include `provenance` and `sbom`.
+
+```console
+$ 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
+
+```console
+$ 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"
+ }
+ ]
+}
+```
+
+### 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 5418ce39..212b43cc 100644
--- a/docs/reference/buildx_history_logs.md
+++ b/docs/reference/buildx_history_logs.md
@@ -5,12 +5,61 @@ Print the logs of a build
### Options
-| Name | Type | Default | Description |
-|:----------------|:---------|:--------|:--------------------------------------------------|
-| `--builder` | `string` | | Override the configured builder instance |
-| `-D`, `--debug` | `bool` | | Enable debug logging |
-| `--progress` | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
+| 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) |
+## 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.
+
+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
+
+```console
+$ 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
+...
+```
+
+By default, this shows logs for the most recent build on the current builder.
+
+### Print logs for a specific build
+
+To print logs for a specific build, use a build ID or offset:
+
+```console
+# Using a build ID
+docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history logs ^1
+```
+
+### Set type of progress output (--progress)
+
+```console
+$ 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}
+...
+```
diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md
index e63224b1..88a7ce34 100644
--- a/docs/reference/buildx_history_ls.md
+++ b/docs/reference/buildx_history_ls.md
@@ -5,15 +5,98 @@ List build records
### Options
-| Name | Type | Default | Description |
-|:----------------|:--------------|:--------|:---------------------------------------------|
-| `--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 |
+| 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 |
+## Description
+
+List completed builds recorded by the active builder. Each entry includes the
+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
+
+```console
+$ 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 failed builds (--filter)
+
+```console
+docker buildx history ls --filter status=error
+```
+
+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
+```
+
+### List builds from the current project (--local)
+
+```console
+docker buildx history ls --local
+```
+
+### Display full output without truncation (--no-trunc)
+
+```console
+docker buildx history ls --no-trunc
+```
+
+### Format output (--format)
+
+**JSON output**
+
+```console
+$ 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"
+ }
+]
+```
+
+**Go template output**
+
+```console
+$ 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 50ed35ff..e0817b41 100644
--- a/docs/reference/buildx_history_open.md
+++ b/docs/reference/buildx_history_open.md
@@ -13,3 +13,27 @@ 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.
+
+## Examples
+
+### Open the most recent build in Docker Desktop
+
+```console
+docker buildx history open
+```
+
+By default, this opens the most recent build on the current builder.
+
+### Open a specific build
+
+```console
+# 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 34bbf14d..dedf1a0c 100644
--- a/docs/reference/buildx_history_rm.md
+++ b/docs/reference/buildx_history_rm.md
@@ -14,3 +14,36 @@ Remove build records
+## Description
+
+Remove one or more build records from the current builder’s history. You can
+remove specific builds by ID or offset, or delete all records at once using
+the `--all` flag.
+
+## Examples
+
+### Remove a specific build
+
+```console
+# Using a build ID
+docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt
+
+# Or using a relative offset
+docker buildx history rm ^1
+```
+
+### Remove multiple builds
+
+```console
+# 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
+
+```console
+docker buildx history rm --all
+```
diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md
index 54362b1a..2b448145 100644
--- a/docs/reference/buildx_history_trace.md
+++ b/docs/reference/buildx_history_trace.md
@@ -5,13 +5,65 @@ Show the OpenTelemetry trace of a build record
### Options
-| Name | Type | Default | Description |
-|:----------------|:---------|:--------------|:-----------------------------------------|
-| `--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 |
-| `-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 |
+## Description
+
+View the OpenTelemetry trace for a completed build. This command loads the
+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
+
+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
+
+```console
+# 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 (--addr)
+
+```console
+# 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 (--compare)
+
+Compare two specific builds by name:
+
+```console
+# 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.