Xcode Cloud with asc

Manage Xcode Cloud products, workflows, and build runs through the App Store Connect API.

Authentication

asc auth login --key-id <id> --issuer-id <id> --private-key-path ~/.asc/AuthKey.p8

How to Navigate (CAEOAS Affordances)

Every JSON response contains an "affordances" field with ready-to-run commands — IDs already filled in. This means you never need to remember or copy-paste IDs manually: just run the command from the affordance of the previous response.

For example, after listing products, the response tells you exactly what to run next:

{
  "id": "prod-abc123",
  "name": "My App",
  "affordances": {
    "listWorkflows": "asc xcode-cloud workflows list --product-id prod-abc123"
  }
}

And after listing workflows, the startBuild affordance appears — but only when the workflow is enabled. If startBuild is missing, the workflow is disabled (isEnabled: false) and cannot be triggered.

{
  "id": "wf-xyz",
  "name": "CI Build",
  "isEnabled": true,
  "affordances": {
    "startBuild": "asc xcode-cloud builds start --workflow-id wf-xyz",
    "listBuildRuns": "asc xcode-cloud builds list --workflow-id wf-xyz"
  }
}

Typical Workflows

Trigger a build (step by step)

# 1. Find the Xcode Cloud product for your app
asc xcode-cloud products list --app-id 6443417124 --pretty

# 2. Copy the listWorkflows affordance from the response and run it
asc xcode-cloud workflows list --product-id prod-abc123 --pretty

# 3. Copy the startBuild affordance from the workflow you want and run it
asc xcode-cloud builds start --workflow-id wf-xyz --pretty

Or as a script:

PRODUCT_ID=$(asc xcode-cloud products list --app-id APP_ID | jq -r '.data[0].id')
WORKFLOW_ID=$(asc xcode-cloud workflows list --product-id "$PRODUCT_ID" \
  | jq -r '.data[] | select(.name == "CI Build") | .id')
asc xcode-cloud builds start --workflow-id "$WORKFLOW_ID"

Check build status

asc xcode-cloud builds get --build-run-id run-99 --pretty

Look at executionProgress first: if it's COMPLETE, check completionStatus to see if it passed or failed.

See recent builds at a glance

asc xcode-cloud builds list --workflow-id wf-xyz --output table

Clean build (clears derived data)

asc xcode-cloud builds start --workflow-id wf-xyz --clean

Reading Build Results

executionProgress — where is the build now?

Value	Meaning
PENDING	Queued, not started yet
RUNNING	Actively building
COMPLETE	Done — check completionStatus

completionStatus — did it succeed? (only set when COMPLETE)

Value	Meaning	hasFailed
SUCCEEDED	All actions passed	false
FAILED	One or more actions failed	true
ERRORED	Infrastructure/system error	true
CANCELED	Manually cancelled	false
SKIPPED	Build was skipped	false

Full Command Reference

See commands.md for all flags and examples.