Feat: support format validation

Makefile

@@ -211,7 +211,8 @@ INTEGRATION_TEST_SUITES := \
 	TestCLIKernelSet \
 	TestCLIAnonymousVolumes \
 	TestCLINotFound \
-	TestCLINoParallelCases
+	TestCLINoParallelCases \
+	TestCLIFormatValidation
 
 empty :=
 space := $(empty) $(empty)

Sources/ContainerCommands/Builder/BuilderStatus.swift

@@ -41,6 +41,10 @@ extension Application {
 
         public init() {}
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         public func run() async throws {
             do {
                 let client = ContainerClient()

Sources/ContainerCommands/Container/ContainerStats.swift

@@ -42,6 +42,10 @@ extension Application {
 
         public init() {}
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         public func run() async throws {
             if format == .json || noStream {
                 // Static mode - get stats once and exit

Sources/ContainerCommands/Image/ImageList.swift

@@ -44,6 +44,10 @@ extension Application {
         @OptionGroup
         public var logOptions: Flags.Logging
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         public mutating func run() async throws {
             let containerSystemConfig: ContainerSystemConfig = try await ConfigurationLoader.load()
             try Self.validate(quiet: quiet, verbose: verbose)

Sources/ContainerCommands/ListFormat.swift

@@ -15,10 +15,24 @@
 //===----------------------------------------------------------------------===//
 
 import ArgumentParser
+import ContainerizationError
 
 public enum ListFormat: String, CaseIterable, ExpressibleByArgument, Sendable {
     case json
     case table
     case yaml
     case toml
+
+    /// Throws if `self` is not in `supported`. Use from a command's `validate()`
+    /// so unimplemented formats fail fast with a clear error instead of silently
+    /// falling through to table output.
+    public func ensureSupported(_ supported: Set<ListFormat>) throws {
+        if !supported.contains(self) {
+            let list = supported.map(\.rawValue).sorted().joined(separator: ", ")
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "--format \(self.rawValue) is not supported for this command; supported: \(list)"
+            )
+        }
+    }
 }

Sources/ContainerCommands/System/SystemDF.swift

@@ -33,6 +33,10 @@ extension Application {
 
         public init() {}
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         public func run() async throws {
             let stats = try await ClientDiskUsage.get()
 

Sources/ContainerCommands/System/SystemStatus.swift

@@ -39,6 +39,10 @@ extension Application {
 
         public init() {}
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         struct PrintableStatus: Codable {
             let status: String
             let appRoot: String

Sources/ContainerCommands/Volume/VolumeList.swift

@@ -39,6 +39,10 @@ extension Application.VolumeCommand {
 
         public init() {}
 
+        public func validate() throws {
+            try format.ensureSupported([.json, .table])
+        }
+
         public func run() async throws {
             let volumes = try await ClientVolume.list()
 

Tests/CLITests/Subcommands/TestCLIFormatValidation.swift

@@ -0,0 +1,80 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Testing
+
+/// Verifies that commands which only implement `--format json|table` reject
+/// `--format yaml` and `--format toml` instead of silently falling through to
+/// table output. As each command grows real yaml/toml support, drop the
+/// corresponding cases from these tests.
+@Suite(.serialSuites)
+final class TestCLIFormatValidation: CLITest {
+
+    private func expectRejected(_ args: [String], format: String) throws {
+        let (_, _, error, status) = try run(arguments: args)
+        #expect(status != 0, "Expected non-zero exit for --format \(format) on \(args.joined(separator: " "))")
+        #expect(error.contains("--format \(format) is not supported"))
+    }
+
+    @Test func testImageListRejectsYAML() throws {
+        try expectRejected(["image", "list", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testImageListRejectsTOML() throws {
+        try expectRejected(["image", "list", "--format", "toml"], format: "toml")
+    }
+
+    @Test func testContainerStatsRejectsYAML() throws {
+        try expectRejected(["stats", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testContainerStatsRejectsTOML() throws {
+        try expectRejected(["stats", "--format", "toml"], format: "toml")
+    }
+
+    @Test func testSystemDFRejectsYAML() throws {
+        try expectRejected(["system", "df", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testSystemDFRejectsTOML() throws {
+        try expectRejected(["system", "df", "--format", "toml"], format: "toml")
+    }
+
+    @Test func testBuilderStatusRejectsYAML() throws {
+        try expectRejected(["builder", "status", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testBuilderStatusRejectsTOML() throws {
+        try expectRejected(["builder", "status", "--format", "toml"], format: "toml")
+    }
+
+    @Test func testVolumeListRejectsYAML() throws {
+        try expectRejected(["volume", "list", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testVolumeListRejectsTOML() throws {
+        try expectRejected(["volume", "list", "--format", "toml"], format: "toml")
+    }
+
+    @Test func testSystemStatusRejectsYAML() throws {
+        try expectRejected(["system", "status", "--format", "yaml"], format: "yaml")
+    }
+
+    @Test func testSystemStatusRejectsTOML() throws {
+        try expectRejected(["system", "status", "--format", "toml"], format: "toml")
+    }
+}