Skip to content

Instantly share code, notes, and snippets.

@steipete
Created June 26, 2025 11:18
Show Gist options
  • Save steipete/4fff3760a1244cb1ab9c1afab957d06b to your computer and use it in GitHub Desktop.
Save steipete/4fff3760a1244cb1ab9c1afab957d06b to your computer and use it in GitHub Desktop.
XcodeBuildMCP but converted to a markdown.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment