Build macOS App

Build any native macOS Xcode project from the command line using xcodebuild.

Finding the Project

Before building, locate the Xcode project or workspace:

find . -maxdepth 2 -name "*.xcodeproj" -o -name "*.xcworkspace" | head -5

Then list available schemes:

xcodebuild -list -project "YourApp.xcodeproj" 2>/dev/null | grep -A 20 "Schemes:"

Build Command

Use this command template, replacing the project path and scheme:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild build \
  -project "YourApp.xcodeproj" \
  -scheme "YourApp" \
  -configuration Debug \
  -destination "platform=macOS" \
  2>&1 | grep -E "(BUILD SUCCEEDED|BUILD FAILED|error:)" | head -20

For workspaces (projects with SPM dependencies or CocoaPods):

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild build \
  -workspace "YourApp.xcworkspace" \
  -scheme "YourApp" \
  -configuration Debug \
  -destination "platform=macOS" \
  2>&1 | grep -E "(BUILD SUCCEEDED|BUILD FAILED|error:)" | head -20

Interpreting Results

• BUILD SUCCEEDED -- the build passed, report success to the user.
• BUILD FAILED with error: lines -- read each error, identify the source file and line, and help the user fix them. After fixing, re-run the build to verify.
• If the output is empty or unclear, re-run without the grep filter to get full output for diagnosis.

When to Build

• After making code changes, if the user asks to verify they compile
• When the user explicitly says "build", "compile", or "check if it builds"
• After fixing build errors, to confirm the fix worked

Xcode Beta Toolchains

If the project targets a beta SDK (e.g., macOS 26 Tahoe), you may need to point to the beta Xcode:

DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer xcodebuild build ...

Check which Xcode is available:

ls /Applications/ | grep -i xcode

Common Build Failures

Error	Fix
no such module 'Sparkle'	SPM dependency not resolved. Try xcodebuild -resolvePackageDependencies first
no signing identity found	Set CODE_SIGN_IDENTITY="" and CODE_SIGNING_ALLOWED=NO for command-line builds
SDK "macosx" cannot be located	Wrong DEVELOPER_DIR. Check Xcode installation path
scheme not found	Run xcodebuild -list to see available schemes