# 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
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.
-
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.
- Replace
-
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.
- Use
-
iOS Device App (Generic):
xcodebuild -scheme <scheme_name> -destination 'generic/platform=iOS' build
To remove intermediate build files and products:
xcodebuild -workspace <workspace_name>.xcworkspace -scheme <scheme_name> clean
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
To get a list of all available simulators, their UDIDs, and their state:
xcrun simctl list devices available --json
-
Boot a simulator:
xcrun simctl boot <simulator_udid>
-
Shutdown a simulator:
xcrun simctl shutdown <simulator_udid>
-
Open the Simulator App:
open -a 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>
- OSLog:
Note: devicectl
is available in Xcode 15 and later. Devices must be connected via USB or Wi-Fi and trusted.
To list all connected physical devices:
xcrun devicectl list 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).
The axe
tool is used for UI interaction with simulators. It must be installed separately.
- Installation (Homebrew):
brew install cameroncooke/axe/axe
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>
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"
After a successful build, the path to the .app
bundle can be found by inspecting the build settings.
- Run
xcodebuild -showBuildSettings ...
for your target. - Find the
BUILT_PRODUCTS_DIR
andFULL_PRODUCT_NAME
values. - The path is
BUILT_PRODUCTS_DIR/FULL_PRODUCT_NAME
.