Add --metadata-file to build command

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Notable changes.
 
+## October 2025
+
+### [0.81.0]
+- Add `--metadata-file` to `build` command (https://github.com/devcontainers/cli/issues/464)
+
 ## July 2025
 
 ### [0.80.0]

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@devcontainers/cli",
 	"description": "Dev Containers CLI",
-	"version": "0.80.1",
+	"version": "0.81.0",
 	"bin": {
 		"devcontainer": "devcontainer.js"
 	},

src/spec-common/injectHeadless.ts

@@ -62,6 +62,7 @@ export interface ResolverParameters {
 	buildxPush: boolean;
 	buildxOutput: string | undefined;
 	buildxCacheTo: string | undefined;
+	buildxMetadtaFile: string | undefined;
 	skipFeatureAutoMapping: boolean;
 	skipPostAttach: boolean;
 	containerSessionDataFolder?: string;

src/spec-node/containerFeatures.ts

@@ -85,6 +85,9 @@ export async function extendImage(params: DockerResolverParameters, config: Subs
 		if (params.buildxCacheTo) {
 			args.push('--cache-to', params.buildxCacheTo);
 		}
+		if (params.buildxMetadataFile) {
+			args.push('--metadata-file', params.buildxMetadataFile);
+		}
 		if (!params.buildNoCache) {
 			params.additionalCacheFroms.forEach(cacheFrom => args.push('--cache-from', cacheFrom));
 		}

src/spec-node/devContainers.ts

@@ -56,6 +56,7 @@ export interface ProvisionOptions {
 	additionalLabels: string[];
 	buildxOutput: string | undefined;
 	buildxCacheTo: string | undefined;
+	buildxMetadataFile: string | undefined;
 	additionalFeatures?: Record<string, string | boolean | Record<string, string | boolean>>;
 	skipFeatureAutoMapping: boolean;
 	skipPostAttach: boolean;
@@ -150,6 +151,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
 		buildxPush: options.buildxPush,
 		buildxOutput: options.buildxOutput,
 		buildxCacheTo: options.buildxCacheTo,
+		buildxMetadtaFile: options.buildxCacheTo,
 		skipFeatureAutoMapping: options.skipFeatureAutoMapping,
 		skipPostAttach: options.skipPostAttach,
 		containerSessionDataFolder: options.containerSessionDataFolder,
@@ -233,6 +235,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
 		additionalLabels: options.additionalLabels,
 		buildxOutput: common.buildxOutput,
 		buildxCacheTo: common.buildxCacheTo,
+		buildxMetadataFile: common.buildxMetadtaFile,
 		platformInfo
 	};
 }

src/spec-node/devContainersSpecCLI.ts

@@ -275,6 +275,7 @@ async function provision({
 		additionalLabels: [],
 		buildxOutput: undefined,
 		buildxCacheTo: addCacheTo,
+		buildxMetadataFile: undefined,
 		additionalFeatures,
 		skipFeatureAutoMapping,
 		skipPostAttach,
@@ -444,6 +445,7 @@ async function doSetUp({
 			additionalLabels: [],
 			buildxOutput: undefined,
 			buildxCacheTo: undefined,
+			buildxMetadataFile: undefined,
 			skipFeatureAutoMapping: false,
 			skipPostAttach: false,
 			skipPersistingCustomizationsFromFeatures: false,
@@ -515,6 +517,7 @@ function buildOptions(y: Argv) {
 		'image-name': { type: 'string', description: 'Image name.' },
 		'cache-from': { type: 'string', description: 'Additional image to use as potential layer cache' },
 		'cache-to': { type: 'string', description: 'A destination of buildx cache' },
+		'metadata-file': { type: 'string', description: 'Write build result metadata to the file. Valid options are the same ones provided to the --metadata-file option of docker buildx build.' },
 		'buildkit': { choices: ['auto' as 'auto', 'never' as 'never'], default: 'auto' as 'auto', description: 'Control whether BuildKit should be used' },
 		'platform': { type: 'string', description: 'Set target platforms.' },
 		'push': { type: 'boolean', default: false, description: 'Push to a container registry.' },
@@ -562,6 +565,7 @@ async function doBuild({
 	'label': buildxLabel,
 	'output': buildxOutput,
 	'cache-to': buildxCacheTo,
+	'metadata-file': buildxMetadataFile,
 	'additional-features': additionalFeaturesJson,
 	'skip-feature-auto-mapping': skipFeatureAutoMapping,
 	'skip-persisting-customizations-from-features': skipPersistingCustomizationsFromFeatures,
@@ -610,6 +614,7 @@ async function doBuild({
 			additionalLabels: [],
 			buildxOutput,
 			buildxCacheTo,
+			buildxMetadataFile,
 			skipFeatureAutoMapping,
 			skipPostAttach: true,
 			skipPersistingCustomizationsFromFeatures: skipPersistingCustomizationsFromFeatures,
@@ -881,6 +886,7 @@ async function doRunUserCommands({
 			additionalLabels: [],
 			buildxOutput: undefined,
 			buildxCacheTo: undefined,
+			buildxMetadataFile: undefined,
 			skipFeatureAutoMapping,
 			skipPostAttach,
 			skipPersistingCustomizationsFromFeatures: false,
@@ -1329,6 +1335,7 @@ export async function doExec({
 			buildxPush: false,
 			additionalLabels: [],
 			buildxCacheTo: undefined,
+			buildxMetadataFile: undefined,
 			skipFeatureAutoMapping,
 			buildxOutput: undefined,
 			skipPostAttach: false,

src/spec-node/featuresCLI/testCommandImpl.ts

@@ -656,6 +656,7 @@ async function generateDockerParams(workspaceFolder: string, args: FeaturesTestC
 		buildxPush: false,
 		buildxOutput: undefined,
 		buildxCacheTo: undefined,
+		buildxMetadataFile: undefined,
 		skipFeatureAutoMapping: false,
 		skipPostAttach: false,
 		skipPersistingCustomizationsFromFeatures: false,

src/spec-node/featuresCLI/utils.ts

@@ -24,6 +24,7 @@ export const staticProvisionParams = {
     buildxPush: false,
     buildxOutput: undefined,
     buildxCacheTo: undefined,
+    buildxMetadataFile: undefined,
     skipPostAttach: false,
 };
 

src/spec-node/singleContainer.ts

@@ -197,6 +197,9 @@ async function buildAndExtendImage(buildParams: DockerResolverParameters, config
 			output.write('Setting BuildKit platform(s): ' + buildParams.buildxPlatform, LogLevel.Trace);
 			args.push('--platform', buildParams.buildxPlatform);
 		}
+		if (buildParams.buildxMetadataFile) {
+			args.push('--metadata-file', buildParams.buildxMetadataFile);
+		}
 		if (buildParams.buildxPush) {
 			args.push('--push');
 		} else {

src/spec-node/utils.ts

@@ -123,6 +123,7 @@ export interface DockerResolverParameters {
 	buildxOutput: string | undefined;
 	buildxCacheTo: string | undefined;
 	platformInfo: PlatformInfo;
+	buildxMetadataFile: string | undefined;
 }
 
 export interface ResolverResult {