> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Xcode cloud

# xcode-cloud

> Trigger and monitor Xcode Cloud workflows and builds

Trigger and monitor Xcode Cloud workflows, build runs, and CI integration.

## Quick Start

```bash theme={null} theme={null}
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

Trigger an Xcode Cloud workflow build:

```bash theme={null} theme={null}
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
```

**Flags:**

* `--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

**Notes:**

* 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

Check the status of an Xcode Cloud build run:

```bash theme={null} theme={null}
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
```

**Flags:**

* `--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

Manage Xcode Cloud workflows:

```bash theme={null} theme={null}
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
```

**Subcommands:**

* `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

**Flags (list):**

* `--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

**Flags (view):**

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

**Flags (create/update):**

* `--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

Manage Xcode Cloud build runs:

```bash theme={null} theme={null}
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"
```

**Subcommands:**

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

**Flags:**

* `--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

List actions for a build run:

```bash theme={null} theme={null}
asc xcode-cloud actions --run-id "BUILD_RUN_ID"
asc xcode-cloud actions --run-id "BUILD_RUN_ID" --output table
```

**Flags:**

* `--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

List artifacts for a build run:

```bash theme={null} theme={null}
asc xcode-cloud artifacts list --run-id "BUILD_RUN_ID"
asc xcode-cloud artifacts list --run-id "BUILD_RUN_ID" --output table
```

**Flags:**

* `--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

List test results for a build run:

```bash theme={null} theme={null}
asc xcode-cloud test-results list --run-id "BUILD_RUN_ID"
asc xcode-cloud test-results list --run-id "BUILD_RUN_ID" --output table
```

**Flags:**

* `--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

List issues for a build run:

```bash theme={null} theme={null}
asc xcode-cloud issues list --run-id "BUILD_RUN_ID"
asc xcode-cloud issues list --run-id "BUILD_RUN_ID" --output table
```

**Flags:**

* `--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

Manage SCM providers and repositories:

```bash theme={null} theme={null}
asc xcode-cloud scm providers list
asc xcode-cloud scm repositories list
asc xcode-cloud scm git-references view --id "REF_ID"
```

**Subcommands:**

* `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

```bash theme={null} theme={null}
# 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

```bash theme={null} theme={null}
#!/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

Xcode Cloud operations can take a long time. Use the `--timeout` flag or set `ASC_TIMEOUT` to increase the request timeout:

```bash theme={null} theme={null}
export ASC_TIMEOUT=1h
asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main" --wait
```

Or use the flag directly:

```bash theme={null} theme={null}
asc xcode-cloud run --app "APP_ID" --workflow "CI" --branch "main" --wait --timeout 2h
```