Overview: Building iOS Applications from the Command Line
Every iOS application destined for TestFlight or the App Store must undergo a strict two-stage packaging process on macOS: compiling source code into an Xcode Archive bundle (.xcarchive), and exporting that archive into a cryptographically signed application package (.ipa). While Xcode's graphical interface provides point-and-click distribution wizards, automated CI/CD pipelines and terminal-driven AI coding workflows rely entirely on Apple's command-line engine: xcodebuild.
Understanding xcodebuild requires establishing clear operational boundaries between local compilation tools and App Store Connect management utilities:
┌────────────────────────────────────────────────────────────────────────┐
│ LOCAL MAC COMPILATION & PACKAGING │
│ │
│ Project Source ──► [ xcodebuild archive ] ──► MyApp.xcarchive │
│ │ │
│ ▼ │
│ ExportOptions.plist ──► [ xcodebuild -exportArchive ] ──► MyApp.ipa │
└───────────────────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ FLIGHTDECK MCP INSPECTION & UPLOAD │
│ │
│ MyApp.ipa ──► [ build_upload_preview ] ──► Validated Metadata │
│ │ │
│ ▼ │
│ [ build_upload_start ] ──► Direct Apple Ingestion │
└────────────────────────────────────────────────────────────────────────┘
FlightDeck Operational Boundary: FlightDeck is an App Store Connect management platform powered by MCP. It contains no compiler, no Xcode toolchain, and does not execute xcodebuild. Compiling and exporting an .ipa is performed locally on your Mac by Xcode tools orchestrated by you or your local AI assistant. Once an .ipa file is generated, FlightDeck provides offline pre-upload validation (build_upload_preview) and native direct upload (build_upload_start).
1. Prerequisites and Xcode Environment Setup
Before executing command-line builds, verify that your macOS environment points to an active Xcode installation rather than the standalone Command Line Tools package.
Active Developer Directory (xcode-select)
The standalone Command Line Tools package includes basic utilities (git, make, clang), but lacks the iOS SDKs, device platforms, and packaging tools required by xcodebuild. Check your current active developer directory:
xcode-select -p
- Valid full Xcode path:
/Applications/Xcode.app/Contents/Developer - Standalone CLI path (insufficient):
/Library/Developer/CommandLineTools
If pointing to the standalone tools, switch to the full Xcode application:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
Verify the installed Xcode version and build number:
xcodebuild -version
# Example output:
# Xcode 16.2
# Build version 16C5032a
2. Discovering Workspace, Project, and Schemes
Apple projects are structured as either a standalone Xcode Project (.xcodeproj) or an Xcode Workspace (.xcworkspace). Workspaces are required whenever your project uses package dependencies, CocoaPods, or frameworks generated by cross-platform tools such as Flutter or React Native.
Run xcodebuild -list in your project root to discover targets, build configurations, and schemes:
# If using a workspace:
xcodebuild -list -workspace MyApp.xcworkspace
# If using a standalone project:
xcodebuild -list -project MyApp.xcodeproj
The output reveals:
- Information about project / workspace: Schemes available for building (e.g.,
MyApp,MyApp-Production). - Build Configurations: Typically
DebugandRelease. Always selectReleasefor distribution packages.
Cross-platform frameworks organize their native code in subdirectories:
- Flutter: Workspace is at
ios/Runner.xcworkspace; Scheme isRunner. - React Native: Workspace is at
ios/<AppName>.xcworkspace; Scheme matches<AppName>.
Always navigate to the ios/ folder or specify the relative workspace path when invoking xcodebuild.
3. Creating the Xcode Archive (.xcarchive)
The first step in generating a distributable iOS app is creating an archive. The archive captures the compiled binary, embedded framework bundles, resource assets, and debugging symbol files (dSYM).
Execute xcodebuild archive targeting the generic iOS device platform:
xcodebuild archive \
-workspace MyApp.xcworkspace \
-scheme MyApp \
-configuration Release \
-destination "generic/platform=iOS" \
-archivePath ./build/MyApp.xcarchive \
CODE_SIGN_STYLE=Automatic \
DEVELOPMENT_TEAM=ABCDE12345
Key Parameters:
-destination "generic/platform=iOS": Directs the compiler to build for real iOS devices (ARM64 architecture) rather than the local Mac Simulator (x86_64 or ARM64 simulator runtime).-archivePath ./build/MyApp.xcarchive: Specifies the destination path for the resulting archive bundle.CODE_SIGN_STYLEandDEVELOPMENT_TEAM: Explicitly specify whether Xcode should automatically manage signing certificates and provisioning profiles or use manual settings defined in your project.
Inside the .xcarchive Bundle:
An .xcarchive is a directory package containing:
MyApp.xcarchive/
├── Info.plist (Archive metadata, creation date, app name)
├── Products/
│ └── Applications/
│ └── MyApp.app/ (Compiled executable and bundled resources)
├── dSYMs/
│ ├── MyApp.app.dSYM (Debug symbol table for crash symbolication)
│ └── Framework.framework.dSYM
└── SCMBlueprint/ (Source control state metadata)
An .xcarchive is an intermediate build product, not an uploadable file. Direct directory bundles cannot be submitted to App Store Connect. Attempting to upload an .xcarchive directly will be rejected by both Apple ingestion APIs and FlightDeck's pre-upload validator.
4. Configuring ExportOptions.plist
The second step converts the .xcarchive into a signed .ipa package using -exportArchive. This command requires an ExportOptions.plist configuration file that defines the distribution channel, signing style, and asset options.
Create an ExportOptions.plist file in your workspace:
For App Store & TestFlight Distribution:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key>
<string>app-store-connect</string>
<key>teamID</key>
<string>ABCDE12345</string>
<key>signingStyle</key>
<string>automatic</string>
<key>stripSwiftSymbols</key>
<true/>
<key>uploadSymbols</key>
<true/>
</dict>
</plist>
For Ad Hoc Direct Distribution (Testing on Registered UDIDs):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key>
<string>release-testing</string>
<key>teamID</key>
<string>ABCDE12345</string>
<key>signingStyle</key>
<string>automatic</string>
<key>stripSwiftSymbols</key>
<true/>
</dict>
</plist>
Key Configuration Elements:
method: Specifies the export channel. In modern Xcode toolchains (Xcode 15+), preferred values areapp-store-connect(App Store and TestFlight),release-testing(Ad Hoc testing on registered devices),debugging(development builds), andenterprise. Legacy aliases (app-store,ad-hoc,development) remain recognized for backward compatibility. Check your installed Xcode options withxcodebuild -help.teamID: Your 10-character Apple Developer Team ID (visible in your Apple Developer account membership page).signingStyle:automatic(Xcode resolves certificates and profiles via your Apple ID account session) ormanual(requires explicitprovisioningProfilesmapping dictionary).uploadSymbols: Whentrue, packages and uploads dSYM files to Apple so App Store Connect crash logs and TestFlight feedback are automatically symbolicated.- Bitcode Deprecation: Bitcode was deprecated in Xcode 14 and is removed in modern Xcode releases. Do not specify legacy bitcode keys in your export configuration; Apple ingestion rejects archives with bitcode instructions.
Inspecting Installed Toolchain Options: To see every ExportOptions.plist key and export method supported by your exact Xcode version, execute:
```bash
xcodebuild -help
```
Scroll to the Available keys for -exportOptionsPlist: section for authoritative options supported on your machine.
5. Exporting the Signed IPA Package
With the archive and ExportOptions.plist prepared, execute -exportArchive:
xcodebuild -exportArchive \
-archivePath ./build/MyApp.xcarchive \
-exportPath ./build/export \
-exportOptionsPlist ./ExportOptions.plist \
-allowProvisioningUpdates
The -allowProvisioningUpdates flag permits xcodebuild to communicate with the Apple Developer Portal to fetch or update provisioning profiles if your Apple Account is configured in Xcode settings.
Upon successful completion, the ./build/export directory contains:
MyApp.ipa: The compressed, code-signed iOS application package.DistributionSummary.plist: Summary of applied certificates, profiles, and embedded entitlements.Packaging.log&ExportOptions.plist: Detailed audit records of the export process.
6. Verifying Code Signing, Entitlements, and Archive Structure
Before submitting or uploading your .ipa, verify its code signature and embedded entitlements using Apple's command-line utilities.
IPA Container vs Code Object: An .ipa file is a ZIP container, not a Mach-O code object. Executing codesign -dvv MyApp.ipa directly will fail with code object is not signed at all. To verify signatures and entitlements, inspect the .app bundle directly inside the .xcarchive, or inspect the extracted payload.
1. Inspect Code Signature on the Archive Bundle
Inspect the compiled .app bundle inside the .xcarchive before or alongside export:
codesign -dvvv ./build/MyApp.xcarchive/Products/Applications/MyApp.app
Look for:
Authority=Apple Distribution: Your Organization (ABCDE12345)(for App Store) orApple Development(for local development).TeamIdentifier=ABCDE12345.Sealed Resources=version 2, rules 13, files 128(valid seal).
2. Verify Embedded Entitlements
Inspect the entitlements embedded in the signed binary:
codesign -d --entitlements :- ./build/MyApp.xcarchive/Products/Applications/MyApp.app
Verify that required capabilities (e.g., aps-environment, com.apple.developer.associated-domains, or keychain-access-groups) match your application configuration.
3. Verify the Exported IPA Bundle Directly
To verify the application bundle inside the exported .ipa without polluting your project directory:
# Unpack payload to a temporary directory
unzip -q ./build/export/MyApp.ipa -d /tmp/inspect_ipa
# Verify bundle signature and entitlements
codesign -dvvv /tmp/inspect_ipa/Payload/*.app
codesign -d --entitlements :- /tmp/inspect_ipa/Payload/*.app
# Inspect binary architecture (must include arm64 for real devices)
file /tmp/inspect_ipa/Payload/*.app/* | grep "Mach-O"
# Clean up
rm -rf /tmp/inspect_ipa
4. Inspect Metadata and Provisioning Without Unzipping to Disk
You can stream and inspect the embedded Info.plist and .mobileprovision directly using unzip -p:
# Inspect CFBundleIdentifier, marketing version, and build number
unzip -p ./build/export/MyApp.ipa 'Payload/*.app/Info.plist' | plutil -p - | grep -E "CFBundleIdentifier|CFBundleShortVersionString|CFBundleVersion"
# Inspect the embedded provisioning profile
unzip -p ./build/export/MyApp.ipa 'Payload/*.app/embedded.mobileprovision' | security cms -D | plutil -p -
7. Natural-Language Prompts for Your AI Assistant
When working in an AI-powered IDE (Cursor, Claude Code, Windsurf, or Antigravity), use a structured prompt to orchestrate local compilation and export safely without accidental uploads:
Inspect this iOS project and help me create a signed release IPA. Determine the correct workspace, scheme, configuration, signing method, and export options. Show me the build commands and any signing changes before executing them. Verify the resulting archive and IPA. Do not upload the binary or modify App Store Connect.
What Your AI Assistant Does:
- Scans project files to detect whether CocoaPods, Swift Package Manager, Flutter, or React Native is in use.
- Identifies the primary workspace (
.xcworkspace) or project (.xcodeproj) and queries schemes withxcodebuild -list. - Prepares an appropriate
ExportOptions.plisttargetingapp-store-connectwith your team ID. - Generates and executes the
xcodebuild archiveandxcodebuild -exportArchivecommands. - Verifies the resulting
.appbundle signature and entitlements inside the archive usingcodesign -dvvv.
8. Post-Export Pre-Upload Inspection with FlightDeck
Once the .ipa package has been exported to disk, switch to FlightDeck's MCP capabilities to validate the binary against your App Store Connect app record:
Run a pre-upload check on my newly exported IPA at ./build/export/MyApp.ipa for app "Quest Companion". Verify bundle identifier, marketing version, and build number before we proceed.
What FlightDeck MCP Does:
FlightDeck executes build_upload_preview:
- Extracts
CFBundleIdentifier,CFBundleShortVersionString,CFBundleVersion, and platform without shell execution or script evaluation. - Calculates streaming SHA-256 and MD5 cryptographic checksums.
- Verifies that the
.ipabundle identifier matches the target application in App Store Connect. - Returns a structured preview confirming readiness for upload.
For a detailed analysis of all pre-upload checks, see the Pre-Upload Binary Validation Guide.
9. Troubleshooting Common Archive and Export Failures
1. No signing certificate "iOS Distribution" found
- Cause: Your macOS Keychain lacks a valid Apple Distribution certificate matching your Team ID, or the certificate is missing its private key.
- Resolution: Open Xcode > Settings > Accounts > Manage Certificates and click + > Apple Distribution to generate or download a certificate. See iOS Code Signing Explained.
2. Profile doesn't include the aps-environment entitlement
- Cause: Your project enabled Push Notifications, but your App Store provisioning profile was generated before adding the Push capability in the Apple Developer Portal.
- Resolution: Regenerate the provisioning profile in the Apple Developer Portal or use
-allowProvisioningUpdateswith automatic signing.
3. Archive upload failed: Bitcode is deprecated
- Cause: Legacy bitcode flags or bitcode-enabled dependencies are included in the build configuration.
- Resolution: Apple deprecated Bitcode starting in Xcode 14 and rejects uploads containing bitcode instructions. Ensure
ENABLE_BITCODE = NOin your target build settings and omit legacy bitcode keys from your export configuration.
4. Mismatched bundle identifier in FlightDeck preview
- Cause: The
CFBundleIdentifierinInfo.plistdoes not match the bundle ID registered with the target App Store Connect app ID. - Resolution: Correct the bundle identifier in your Xcode target build settings, re-export, and re-run
build_upload_preview.