asc-builds-upload（asc 构建上传）

asc Builds Upload

Upload and distribute builds via App Store Connect. See workflow.md for the full end-to-end flow and error handling.

Commands

Upload a build

asc builds upload \
  --app-id <APP_ID> \
  --file MyApp.ipa \
  --version 1.0.0 \
  --build-number 42 \
  [--platform ios|macos|tvos|visionos]  # auto-detected from extension
  [--wait]                               # poll until processing completes

Platform is auto-detected: .pkg → macos, everything else → ios.

Poll status

asc builds uploads get --upload-id <UPLOAD_ID>
asc builds uploads list --app-id <APP_ID>
asc builds uploads delete --upload-id <UPLOAD_ID>

TestFlight distribution

# Add build to a beta group
asc builds add-beta-group --build-id <BUILD_ID> --beta-group-id <GROUP_ID>

# Remove build from a beta group
asc builds remove-beta-group --build-id <BUILD_ID> --beta-group-id <GROUP_ID>

# Set "What's New" notes (creates or updates the localization)
asc builds update-beta-notes \
  --build-id <BUILD_ID> \
  --locale en-US \
  --notes "Bug fixes and improvements."

Link build to version

asc versions set-build --version-id <VERSION_ID> --build-id <BUILD_ID>

Required before submitting a version for App Store review.

Resolve App ID

See project-context.md — check .asc/project.json before asking the user or running asc apps list.

Typical Workflow

APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')
# If empty: ask user or run `asc apps list | jq -r '.data[0].id'`

# 1. Get the next build number automatically
BUILD_NUMBER=$(asc builds next-number --app-id "$APP_ID" --version 1.2.0 --platform ios)

# 2. Upload and wait
asc builds upload --app-id "$APP_ID" --file MyApp.ipa \
  --version 1.2.0 --build-number "$BUILD_NUMBER" --wait

# 3. Get the processed build ID
BUILD_ID=$(asc builds list --app-id $APP_ID | jq -r '.data[0].id')

# 4. Distribute to beta group
asc builds add-beta-group --build-id $BUILD_ID --beta-group-id $GROUP_ID

# 5. Set notes
asc builds update-beta-notes --build-id $BUILD_ID --locale en-US --notes "..."

# 6. Link to version and submit
asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID
asc versions submit --version-id $VERSION_ID

CAEOAS Affordances

Upload responses include affordances with ready-to-run follow-up commands:

{
  "data": [{
    "affordances": {
      "checkStatus": "asc builds uploads get --upload-id abc123",
      "listBuilds": "asc builds list --app-id 123456789"
    },
    "state": "COMPLETE"
  }]
}

listBuilds only appears when state == "COMPLETE". Use affordances to navigate without memorizing IDs.

Reference

See workflow.md for:

• Full 5-step upload API flow internals
• Build upload states and polling logic
• Error scenarios and troubleshooting