XcodeBuildMCP but converted to a markdown.

XcodeBuild.md

xcode-manual.md

# Xcode and Swift Command-Line Manual for Agents

This document provides a concise guide to performing common Xcode and Swift development tasks using terminal commands. It is intended to be a direct, actionable reference for AI agents, replacing the need for an MCP.

## 1. Project and Workspace Operations

### Listing Schemes, Configurations, and Targets

To understand the buildable components of a project:

- **For `.xcodeproj`:**
  ```bash
  xcodebuild -list -project <project_name>.xcodeproj

• For .xcworkspace:

  xcodebuild -list -workspace <workspace_name>.xcworkspace

Showing Build Settings

To inspect the build settings for a specific scheme and configuration:

• For workspaces:

  xcodebuild -showBuildSettings -workspace <workspace_name>.xcworkspace -scheme <scheme_name>

• For projects:

  xcodebuild -showBuildSettings -project <project_name>.xcodeproj -scheme <scheme_name>

Note: Add -configuration <Debug|Release> to specify a configuration.

Building Projects and Workspaces

• General Build Command:

  xcodebuild -workspace <workspace_name>.xcworkspace -scheme <scheme_name> -configuration <config_name> -destination '<destination_specifier>'

  • Replace -workspace with -project for project-based builds.
  • The -destination flag is crucial for specifying the target platform and device.

• macOS App:

  xcodebuild -scheme <scheme_name> -destination 'platform=macOS,arch=arm64' build

• iOS Simulator App:

  xcodebuild -scheme <scheme_name> -destination 'platform=iOS Simulator,name=iPhone 15 Pro,OS=latest' build

  • Use xcrun simctl list devices to find available simulator names.

• iOS Device App (Generic):

  xcodebuild -scheme <scheme_name> -destination 'generic/platform=iOS' build

Cleaning Build Artifacts

To remove intermediate build files and products:

xcodebuild -workspace <workspace_name>.xcworkspace -scheme <scheme_name> clean

2. Swift Package Manager

All swift commands should be run from the directory containing the Package.swift file.

• Build:

  swift build

  For release configuration: swift build -c release

• Test:

  swift test

  To run tests in parallel: swift test --parallel

• Run Executable:

  swift run <executable_name> [arguments...]

  If there is only one executable, <executable_name> is optional.

• Clean:

  swift package clean

3. Simulator Management (xcrun simctl)

Listing Simulators

To get a list of all available simulators, their UDIDs, and their state:

xcrun simctl list devices available --json

Controlling Simulators

• Boot a simulator:

  xcrun simctl boot <simulator_udid>

• Shutdown a simulator:

  xcrun simctl shutdown <simulator_udid>

• Open the Simulator App:

  open -a Simulator

Interacting with a Booted Simulator

• Install an app:

  xcrun simctl install <simulator_udid> <path_to_app_bundle>

• Uninstall an app:

  xcrun simctl uninstall <simulator_udid> <bundle_identifier>

• Launch an app:

  xcrun simctl launch <simulator_udid> <bundle_identifier>

• Terminate an app:

  xcrun simctl terminate <simulator_udid> <bundle_identifier>

• Capture a screenshot:

  xcrun simctl io <simulator_udid> screenshot screenshot.png

• Capture Logs:

  • OSLog: xcrun simctl spawn <simulator_udid> log stream --level=debug --predicate 'subsystem == "<bundle_identifier>"'
  • Console Output: xcrun simctl launch --console-pty <simulator_udid> <bundle_identifier>

4. Physical Device Management (xcrun devicectl)

Note: devicectl is available in Xcode 15 and later. Devices must be connected via USB or Wi-Fi and trusted.

Listing Devices

To list all connected physical devices:

xcrun devicectl list devices

Interacting with Devices

• Install an app:

  xcrun devicectl device install app --device <device_udid> <path_to_app_bundle>

• Launch an app:

  xcrun devicectl device launch app --device <device_udid> <bundle_identifier>

  Add --console to stream device logs to the terminal (Xcode 16+).

• Stop an app:

  xcrun devicectl device process terminate --device <device_udid> --pid <process_id>

  (The PID is returned by the launch command).

5. UI Automation (axe)

The axe tool is used for UI interaction with simulators. It must be installed separately.

• Installation (Homebrew):

  brew install cameroncooke/axe/axe

Common axe Commands

All commands require the --udid <simulator_udid> flag to target a specific booted simulator.

• Get UI Hierarchy:

  axe describe-ui --udid <simulator_udid>

• Tap a coordinate:

  axe tap -x <x_coord> -y <y_coord> --udid <simulator_udid>

• Swipe:

  axe swipe --start-x <x1> --start-y <y1> --end-x <x2> --end-y <y2> --udid <simulator_udid>

• Type Text:

  axe type "<text_to_type>" --udid <simulator_udid>

• Press a Hardware Button:

  axe button <home|lock|side-button> --udid <simulator_udid>

6. App Information

Getting Bundle ID

The bundle identifier is required for many simctl and devicectl commands. It can be extracted from the Info.plist file within the .app bundle.

/usr/libexec/PlistBuddy -c "Print :CFBundleIdentifier" "<path_to_app_bundle>/Info.plist"

Getting App Path from Build Settings

After a successful build, the path to the .app bundle can be found by inspecting the build settings.

1. Run xcodebuild -showBuildSettings ... for your target.
2. Find the BUILT_PRODUCTS_DIR and FULL_PRODUCT_NAME values.
3. The path is BUILT_PRODUCTS_DIR/FULL_PRODUCT_NAME.