@@ -29,6 +29,7 @@ xcodecloud
2929│ └── get <id> → Get details for a workflow
3030├── builds
3131│ ├── list --workflow <id>→ List build runs for a workflow
32+ │ ├── find <commit-sha> → Find a build by commit SHA
3233│ ├── get <id> → Get details for a build run
3334│ ├── start <workflow-id>→ Start a new build run
3435│ ├── watch <build-id> → Watch a build until completion
@@ -287,15 +288,27 @@ xcodecloud workflows get <workflow-id>
287288#### Builds
288289
289290``` bash
290- # List builds for a workflow (--workflow is required)
291+ # List builds for a workflow (--workflow or --workflow-name is required)
291292xcodecloud builds list --workflow < workflow-id>
292293
294+ # List builds by workflow name (instead of ID)
295+ xcodecloud builds list --product < product-id> --workflow-name " Release"
296+
293297# Filter by status (SUCCEEDED, FAILED, ERRORED, CANCELED, SKIPPED)
294298xcodecloud builds list --workflow < workflow-id> --status failed
295299
300+ # Filter by commit SHA
301+ xcodecloud builds list --workflow < workflow-id> --commit abc1234
302+
296303# Show only running builds
297304xcodecloud builds list --workflow < workflow-id> --running
298305
306+ # Find a build by commit SHA (searches across all products and workflows)
307+ xcodecloud builds find abc1234
308+
309+ # Narrow the search to a specific product
310+ xcodecloud builds find abc1234 --product < product-id>
311+
299312# Get build details
300313xcodecloud builds get < build-id>
301314
@@ -423,14 +436,18 @@ List commands support client-side filtering. Filters are applied after fetching
423436| ` workflows list ` | ` --name <text> ` | Filter by name (case-insensitive substring match) |
424437| ` workflows list ` | ` --enabled ` | Show only enabled workflows |
425438| ` workflows list ` | ` --disabled ` | Show only disabled workflows |
426- | ` builds list ` | ` --workflow <id> ` | Workflow to list builds for (required) |
439+ | ` builds list ` | ` --workflow <id> ` | Workflow to list builds for (required unless using ` --workflow-name ` ) |
440+ | ` builds list ` | ` --workflow-name <name> ` | Look up workflow by name (requires ` --product ` ) |
441+ | ` builds list ` | ` --product <id> ` | Product ID (required with ` --workflow-name ` ) |
427442| ` builds list ` | ` --status <status> ` | Filter by completion status: ` SUCCEEDED ` , ` FAILED ` , ` ERRORED ` , ` CANCELED ` , ` SKIPPED ` |
428443| ` builds list ` | ` --running ` | Show only builds currently in progress |
444+ | ` builds list ` | ` --commit <sha> ` | Filter by commit SHA prefix |
429445
430446Filters can be combined:
431447
432448``` bash
433449xcodecloud builds list --workflow < id> --status failed
450+ xcodecloud builds list --workflow < id> --commit abc1234
434451xcodecloud products list --name MyApp --type APP
435452```
436453
@@ -458,6 +475,15 @@ xcodecloud builds get ghi789 -o table
458475xcodecloud builds errors ghi789
459476```
460477
478+ ### Quick build lookup
479+
480+ If you know the commit SHA, skip the product/workflow/build chain entirely:
481+
482+ ``` bash
483+ # Find the build for a specific commit and see errors if it failed
484+ xcodecloud builds find abc1234
485+ ```
486+
461487### Scripting examples
462488
463489** Get the latest build status:**
0 commit comments