[GH-ISSUE #764] builds: add `find` subcommand for single-result build lookup by number (ergonomics) #206

New issue

Closed

opened 2026-02-26 21:34:00 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 21:34:00 +03:00

Owner

Originally created by @mithileshchellappan on GitHub (Feb 24, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/764

Summary

Add a builds find subcommand that resolves a single build by its build number (CFBundleVersion) and returns the build ID and metadata with clear exit codes — as ergonomic sugar over the existing builds list --build-number filter.

Context: What Already Works

The CLI already supports build-number lookup via:

asc builds list --app APP_ID --build-number 28

This maps to filter[version] on the /v1/builds endpoint and returns matching builds. The internal findBuildByNumber() helper in internal/cli/shared/build_wait.go also resolves builds by number (used by WaitForBuildByNumber() for upload polling).

What's Missing (UX Gap)

builds list --build-number returns a list response (array), even when the intent is to find exactly one build. For agent workflows, the friction is:

No single-object response — agents must unwrap data[0] from the array and handle the empty-array case
No deterministic exit code — builds list exits 0 whether it finds 0 or 100 matches; agents can't use exit code to branch
Requires --app + --build-number + --version for precision — build numbers can repeat across marketing versions, so finding "build 28 of version 1.2.3" requires combining multiple flags that aren't obvious from --help

A dedicated builds find would provide:

Single-object response (not wrapped in array)
Exit code 1 when no build matches (scriptable)
Clear error when multiple builds match (ambiguous lookup)

Proposal

# Find build by number (returns single object or exits non-zero)
asc builds find --app APP_ID --build-number 28

# With version + platform for precision
asc builds find --app APP_ID --build-number 28 --version 1.2.3 --platform IOS

# Output formats
asc builds find --app APP_ID --build-number 28 --output table

Exit Codes

Code	Meaning
`0`	Exactly one build found
`1`	No build matches
`2`	Multiple builds match (use `--version`/`--platform` to narrow)

Flags

Flag	Required	Description
`--app`	Yes	App Store Connect app ID (or `ASC_APP_ID`)
`--build-number`	Yes	CFBundleVersion to search for
`--version`	No	Marketing version (CFBundleShortVersionString) to narrow results
`--platform`	No	Platform filter: IOS, MAC_OS, TV_OS, VISION_OS
`--output`	No	Output format (default: json)

Implementation

Can reuse existing findBuildByNumber() from internal/cli/shared/build_wait.go, or compose from builds list --build-number with single-result enforcement.

Acceptance Criteria

asc builds find --app APP_ID --build-number 28 returns a single build object (not array)
Exits 1 with clear stderr message if no build matches
Exits 2 with clear stderr message if multiple builds match
--version and --platform narrow the lookup
Tests pass with ASC_BYPASS_KEYCHAIN=1

Use Case

After uploading via external tools (xcodebuild, Xcode Cloud, etc.), agents need to reference the specific build they just uploaded by its known build number. Today this requires parsing array output from builds list; builds find makes it a one-liner with reliable exit codes.

Originally created by @mithileshchellappan on GitHub (Feb 24, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/764 ## Summary Add a `builds find` subcommand that resolves a single build by its build number (CFBundleVersion) and returns the build ID and metadata with clear exit codes — as ergonomic sugar over the existing `builds list --build-number` filter. ## Context: What Already Works The CLI **already supports** build-number lookup via: ```bash asc builds list --app APP_ID --build-number 28 ``` This maps to `filter[version]` on the `/v1/builds` endpoint and returns matching builds. The internal `findBuildByNumber()` helper in `internal/cli/shared/build_wait.go` also resolves builds by number (used by `WaitForBuildByNumber()` for upload polling). ## What's Missing (UX Gap) `builds list --build-number` returns a **list response** (array), even when the intent is to find exactly one build. For agent workflows, the friction is: 1. **No single-object response** — agents must unwrap `data[0]` from the array and handle the empty-array case 2. **No deterministic exit code** — `builds list` exits 0 whether it finds 0 or 100 matches; agents can't use exit code to branch 3. **Requires `--app` + `--build-number` + `--version` for precision** — build numbers can repeat across marketing versions, so finding "build 28 of version 1.2.3" requires combining multiple flags that aren't obvious from `--help` A dedicated `builds find` would provide: - **Single-object response** (not wrapped in array) - **Exit code 1** when no build matches (scriptable) - **Clear error** when multiple builds match (ambiguous lookup) ## Proposal ```bash # Find build by number (returns single object or exits non-zero) asc builds find --app APP_ID --build-number 28 # With version + platform for precision asc builds find --app APP_ID --build-number 28 --version 1.2.3 --platform IOS # Output formats asc builds find --app APP_ID --build-number 28 --output table ``` ### Exit Codes | Code | Meaning | |------|---------| | `0` | Exactly one build found | | `1` | No build matches | | `2` | Multiple builds match (use `--version`/`--platform` to narrow) | ### Flags | Flag | Required | Description | |------|----------|-------------| | `--app` | Yes | App Store Connect app ID (or `ASC_APP_ID`) | | `--build-number` | Yes | CFBundleVersion to search for | | `--version` | No | Marketing version (CFBundleShortVersionString) to narrow results | | `--platform` | No | Platform filter: IOS, MAC_OS, TV_OS, VISION_OS | | `--output` | No | Output format (default: json) | ### Implementation Can reuse existing `findBuildByNumber()` from `internal/cli/shared/build_wait.go`, or compose from `builds list --build-number` with single-result enforcement. ## Acceptance Criteria - `asc builds find --app APP_ID --build-number 28` returns a single build object (not array) - Exits 1 with clear stderr message if no build matches - Exits 2 with clear stderr message if multiple builds match - `--version` and `--platform` narrow the lookup - Tests pass with `ASC_BYPASS_KEYCHAIN=1` ## Use Case After uploading via external tools (xcodebuild, Xcode Cloud, etc.), agents need to reference the specific build they just uploaded by its known build number. Today this requires parsing array output from `builds list`; `builds find` makes it a one-liner with reliable exit codes.