xcode

Xcode CLI Skill

Control Xcode from Claude — build, test, run, clean, archive, and manage simulators and devices.

Prerequisites

The xcode-cli command must be installed. If not available, install it automatically:

which xcode-cli || (cd ${CLAUDE_PLUGIN_ROOT}/agent-harness && python3 -m venv .venv && source .venv/bin/activate && pip install -e . && echo "xcode-cli installed")

If a venv already exists, activate it:

test -f ${CLAUDE_PLUGIN_ROOT}/agent-harness/.venv/bin/activate && source ${CLAUDE_PLUGIN_ROOT}/agent-harness/.venv/bin/activate

System requirements:

• macOS with Xcode installed
• Xcode Command Line Tools (xcode-select --install)
• Python 3.10+

Command Syntax

Command	Action
/xcode build	Build the active scheme
/xcode test	Run tests
/xcode run	Build and run
/xcode clean	Clean build
/xcode stop	Stop running action
/xcode archive	Create archive
/xcode schemes	List schemes
/xcode destinations	List run destinations
/xcode simulators	List simulators
/xcode devices	List physical devices
/xcode open <path>	Open workspace/project
/xcode status	Show session status

CLI Command Reference

Workspace operations:

xcode-cli --json workspace list
xcode-cli --json workspace open "/path/to/Project.xcodeproj"
xcode-cli --json workspace schemes
xcode-cli --json workspace destinations
xcode-cli --json workspace projects
xcode-cli --json workspace targets [--project "ProjectName"]
xcode-cli --json workspace settings [--target "TargetName"] [--config "Debug"]
xcode-cli --json workspace active

Build operations:

xcode-cli --json build build [--scheme "MyApp"] [--destination "..."] [--config "Release"]
xcode-cli --json build run [--scheme "MyApp"] [--destination "..."]
xcode-cli --json build test [--scheme "MyApp"] [--destination "..."] [--test-plan "MyTests"]
xcode-cli --json build clean [--scheme "MyApp"]
xcode-cli --json build stop
xcode-cli --json build archive [--scheme "MyApp"] [--output "/path/to/MyApp.xcarchive"]
xcode-cli --json build status
xcode-cli --json build errors
xcode-cli --json build warnings
xcode-cli --json build test-failures
xcode-cli --json build log

Simulator management:

xcode-cli --json simulator list [--booted] [--available]
xcode-cli --json simulator boot "iPhone 16"
xcode-cli --json simulator shutdown "iPhone 16"
xcode-cli --json simulator install "iPhone 16" "/path/to/MyApp.app"
xcode-cli --json simulator launch "iPhone 16" "com.example.myapp"
xcode-cli --json simulator screenshot "iPhone 16" ~/Desktop/screenshot.png
xcode-cli --json simulator create "My Sim" "com.apple.CoreSimulator.SimDeviceType.iPhone-16" "com.apple.CoreSimulator.SimRuntime.iOS-18-0"
xcode-cli --json simulator delete "My Sim"
xcode-cli --json simulator types
xcode-cli --json simulator runtimes

Device management:

xcode-cli --json device list
xcode-cli --json device info "<udid>"

Editor operations:

xcode-cli --json editor file
xcode-cli --json editor text
xcode-cli --json editor selection
xcode-cli --json editor goto 42
xcode-cli --json editor open "/path/to/file.swift"

Session:

xcode-cli --json session status

Natural Language -> CLI Mapping

User says	CLI command
"Build the project"	build build
"Run the app"	build run
"Run tests"	build test
"Clean and rebuild"	build clean then build build
"Stop the app"	build stop
"Show errors"	build errors
"Any warnings?"	build warnings
"Which tests failed?"	build test-failures
"Show the build log"	build log
"What schemes are there?"	workspace schemes
"List simulators"	simulator list --available
"Boot iPhone 16"	simulator boot "iPhone 16"
"Take a screenshot"	simulator screenshot "iPhone 16" ~/Desktop/screenshot.png
"Connected devices"	device list
"Archive for release"	build archive --scheme "..." --config "Release"
"Open my project"	workspace open "/path/to/Project.xcodeproj"

Destination Specifiers

Common destination formats for --destination:

• iOS Simulator: "platform=iOS Simulator,name=iPhone 16"
• iOS Simulator with OS: "platform=iOS Simulator,name=iPhone 16,OS=18.0"
• macOS: "platform=macOS"
• Any iOS Simulator: "generic/platform=iOS Simulator"
• Specific UDID: "id=<UDID>"

Important

• ALWAYS use --json for query commands (list, status, errors, warnings, schemes, etc.)
• Xcode launches automatically if not already running
• For build/test, prefer specifying --scheme explicitly
• If CLI is not in PATH: source ${CLAUDE_PLUGIN_ROOT}/agent-harness/.venv/bin/activate
• Use --workspace or --project flags when building from command line without Xcode open