​

xcode-cloud

Trigger and monitor Xcode Cloud workflows and builds

​

Quick Start

asc xcode-cloud workflows --app "APP_ID"
asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main"
asc xcode-cloud status --run-id "BUILD_RUN_ID" --wait

​

Subcommands

• run - Trigger an Xcode Cloud workflow build
• status - Check the status of an Xcode Cloud build run
• workflows - Manage Xcode Cloud workflows
• build-runs - Manage Xcode Cloud build runs
• actions - List actions for a build run
• artifacts - List artifacts for a build run
• test-results - List test results for a build run
• issues - List issues for a build run
• scm - Manage SCM providers and repositories
• products - List Xcode Cloud products
• macos-versions - List available macOS versions
• xcode-versions - List available Xcode versions

​

Commands

​

xcode-cloud run

asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main"
asc xcode-cloud run --workflow-id "WORKFLOW_ID" --git-reference-id "REF_ID"
asc xcode-cloud run --app "APP_ID" --workflow "Deploy" --branch "release/1.0" --wait
asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main" --wait --poll-interval 30s --timeout 1h

• --app - App Store Connect app ID (or ASC_APP_ID)
• --workflow - Workflow name to trigger
• --workflow-id - Workflow ID to trigger (alternative to --workflow)
• --branch - Branch or tag name to build
• --git-reference-id - Git reference ID to build (alternative to --branch)
• --wait - Wait for build to complete
• --poll-interval - Poll interval when waiting (default: 10s)
• --timeout - Timeout for Xcode Cloud requests (0 = use ASC_TIMEOUT or 30m default)
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

• Specify workflow by name (requires --app) or by ID (--workflow-id)
• Specify branch/tag by name (--branch) or by ID (--git-reference-id)
• Use --wait to monitor build progress until completion

​

xcode-cloud status

asc xcode-cloud status --run-id "BUILD_RUN_ID"
asc xcode-cloud status --run-id "BUILD_RUN_ID" --output table
asc xcode-cloud status --run-id "BUILD_RUN_ID" --wait
asc xcode-cloud status --run-id "BUILD_RUN_ID" --wait --poll-interval 30s --timeout 1h

• --run-id - Build run ID to check (required)
• --wait - Wait for build to complete
• --poll-interval - Poll interval when waiting (default: 10s)
• --timeout - Timeout for Xcode Cloud requests (0 = use ASC_TIMEOUT or 30m default)
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud workflows

asc xcode-cloud workflows --app "APP_ID"
asc xcode-cloud workflows list --app "APP_ID"
asc xcode-cloud workflows view --id "WORKFLOW_ID"
asc xcode-cloud workflows repository --id "WORKFLOW_ID"
asc xcode-cloud workflows create --file ./workflow.json
asc xcode-cloud workflows update --id "WORKFLOW_ID" --file ./workflow.json
asc xcode-cloud workflows delete --id "WORKFLOW_ID" --confirm

• list - List Xcode Cloud workflows for an app
• view - View details for a workflow
• repository - Get the repository for a workflow
• create - Create a workflow
• update - Update a workflow
• delete - Delete a workflow

• --app - App Store Connect app ID (or ASC_APP_ID)
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

• --id - Workflow ID (required)
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

• --file - Path to workflow JSON payload (required)
• --id - Workflow ID (required for update)
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud build-runs

asc xcode-cloud build-runs --workflow-id "WORKFLOW_ID"
asc xcode-cloud build-runs list --workflow-id "WORKFLOW_ID"
asc xcode-cloud build-runs builds --run-id "BUILD_RUN_ID"

• list - List Xcode Cloud build runs for a workflow
• builds - List builds for a build run

• --workflow-id - Workflow ID to list build runs for
• --run-id - Build run ID to list builds for
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud actions

asc xcode-cloud actions --run-id "BUILD_RUN_ID"
asc xcode-cloud actions --run-id "BUILD_RUN_ID" --output table

• --run-id - Build run ID (required)
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud artifacts

asc xcode-cloud artifacts list --run-id "BUILD_RUN_ID"
asc xcode-cloud artifacts list --run-id "BUILD_RUN_ID" --output table

• --run-id - Build run ID (required)
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud test-results

asc xcode-cloud test-results list --run-id "BUILD_RUN_ID"
asc xcode-cloud test-results list --run-id "BUILD_RUN_ID" --output table

• --run-id - Build run ID (required)
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud issues

asc xcode-cloud issues list --run-id "BUILD_RUN_ID"
asc xcode-cloud issues list --run-id "BUILD_RUN_ID" --output table

• --run-id - Build run ID (required)
• --limit - Maximum results per page (1-200)
• --next - Fetch next page using a links.next URL
• --paginate - Automatically fetch all pages
• --output - Output format: json, table, markdown
• --pretty - Pretty-print JSON output

​

xcode-cloud scm

asc xcode-cloud scm providers list
asc xcode-cloud scm repositories list
asc xcode-cloud scm git-references view --id "REF_ID"

• providers list - List SCM providers
• repositories list - List SCM repositories for a product
• git-references list - List Git references for a repository

​

Workflow Examples

​

Trigger and Monitor Build

# Trigger a build and wait for completion
asc xcode-cloud run \
  --app "123456789" \
  --workflow "CI" \
  --branch "main" \
  --wait

# Check build status
asc xcode-cloud status --run-id "BUILD_RUN_ID"

# View build artifacts
asc xcode-cloud artifacts list --run-id "BUILD_RUN_ID"

# View test results
asc xcode-cloud test-results list --run-id "BUILD_RUN_ID"

​

CI Integration

#!/bin/bash
set -e

# Trigger build
RUN_OUTPUT=$(asc xcode-cloud run \
  --app "$APP_ID" \
  --workflow "CI" \
  --branch "$BRANCH" \
  --output json)

# Extract build run ID
BUILD_RUN_ID=$(echo "$RUN_OUTPUT" | jq -r '.buildRunID')

echo "Build run ID: $BUILD_RUN_ID"

# Wait for build to complete
asc xcode-cloud status --run-id "$BUILD_RUN_ID" --wait

# Check for issues
ISSUES=$(asc xcode-cloud issues list --run-id "$BUILD_RUN_ID" --output json)
ISSUE_COUNT=$(echo "$ISSUES" | jq '.data | length')

if [ "$ISSUE_COUNT" -gt 0 ]; then
  echo "Build has $ISSUE_COUNT issues"
  exit 1
fi

echo "Build completed successfully"

​

Timeouts

export ASC_TIMEOUT=1h
asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main" --wait

asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main" --wait --timeout 2h