/native

Terminal / CI Command Reference — Mac Apps

Production command reference for building, signing, notarizing, packaging, and debugging macOS apps from the terminal or CI. Owns exact flag syntax; reference/distribution.md owns the decision/flow narrative and cross-references back here for command detail — do not duplicate the flow explanation in both files.

Scope: xcodebuild, xcresulttool, codesign, security, notarytool, stapler, spctl, pkgbuild/productbuild/productsign, hdiutil, otool/install_name_tool, atos, log, defaults, and a CI recipe.

1. xcodebuild — Build / Archive / Export

1.1 ExportOptions.plist Variants

<!-- ExportOptions-developer-id.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>teamID</key>
    <string>TEAMID1234</string>
    <key>signingStyle</key>
    <string>manual</string>
    <key>signingCertificate</key>
    <string>Developer ID Application</string>
</dict>
</plist>

Export-method strings. app-store-connect is the current value for App Store submission; app-store is its deprecated predecessor and still accepted by older Xcode. developer-id (direct distribution, notarized) and mac-application (unsigned/local) are the other Mac-relevant values. Pin the string to your CI's Xcode version — xcodebuild -help lists what that toolchain accepts.

2. xcresulttool — Result Bundle Parsing

Xcode 16 changed the result-bundle schema (new structure under actions._values) — pin a parser to the Xcode version in CI or use --legacy.

3. codesign

4. security — Keychain for CI

5. notarytool — Submission and History

• App-specific password: generate at appleid.apple.com, not the account's primary password.
• --keychain-profile is the CI-friendly alternative to passing --apple-id/--team-id/--password inline on every call — set it up once via store-credentials in a keychain accessible to the CI runner (same build.keychain from § 4 works).

6. stapler / spctl

Expected success output includes source=Notarized Developer ID — anything else (source=Unnotarized Developer ID, rejected) means either notarization wasn't submitted, wasn't stapled, or the artifact was modified after signing.

7. pkgbuild / productbuild / productsign

8. hdiutil — DMG Creation

Community wrapper create-dmg scripts this whole sequence (icon positions, background image, window size) — evaluate as a build dependency rather than reimplementing the hdiutil choreography by hand unless the CI environment can't install it.

9. otool / install_name_tool — Embedded Framework Paths

Re-sign the binary after any install_name_tool mutation — changing load commands invalidates the existing signature.

10. atos / Symbolication

A UUID mismatch between the dSYM and the binary produces plausible-looking but wrong symbol names — always verify with dwarfdump --uuid before trusting output.

11. log / log stream — Running App

12. defaults — Reading App Prefs During Debugging

Sandboxed apps store preferences inside the app's container (~/Library/Containers/com.example.myapp/Data/Library/Preferences/) — defaults read <bundle-id> still resolves correctly against the container path, but direct plutil/cat access needs the full container path if bypassing defaults.

13. CI Recipe — GitHub Actions macOS Runner

name: build-sign-notarize
on: [workflow_dispatch]

jobs:
  release:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Import signing certificate
        env:
          P12_BASE64: ${{ secrets.DEVELOPER_ID_P12_BASE64 }}
          P12_PASSWORD: ${{ secrets.DEVELOPER_ID_P12_PASSWORD }}
          KEYCHAIN_PASSWORD: ${{ secrets.CI_KEYCHAIN_PASSWORD }}
        run: |
          echo "$P12_BASE64" | base64 --decode > cert.p12
          security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
          security import cert.p12 -k build.keychain -P "$P12_PASSWORD" -T /usr/bin/codesign
          security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" build.keychain
          rm cert.p12

      - name: Build and archive
        run: |
          xcodebuild archive -scheme App -configuration Release \
            -archivePath build/App.xcarchive

      - name: Export signed app
        run: |
          xcodebuild -exportArchive -archivePath build/App.xcarchive \
            -exportOptionsPlist ExportOptions-developer-id.plist \
            -exportPath build/export

      - name: Verify signature
        run: codesign -dv --verbose=4 build/export/App.app

      - name: Package DMG
        run: |
          mkdir -p staging
          cp -R build/export/App.app staging/
          ln -s /Applications staging/Applications
          hdiutil create -volname "App" -srcfolder staging -ov -format UDZO build/App.dmg

      - name: Notarize
        env:
          AC_PROFILE_CREDS: ${{ secrets.NOTARYTOOL_KEYCHAIN_PROFILE_SETUP }}
        run: |
          xcrun notarytool store-credentials "AC_PROFILE" \
            --apple-id "${{ secrets.APPLE_ID }}" \
            --team-id "${{ secrets.TEAM_ID }}" \
            --password "${{ secrets.APP_SPECIFIC_PASSWORD }}"
          xcrun notarytool submit build/App.dmg --keychain-profile "AC_PROFILE" --wait

      - name: Staple
        run: xcrun stapler staple build/App.dmg

      - name: Verify Gatekeeper acceptance
        run: spctl -a -vvv -t install build/App.dmg || spctl -a -vvv build/App.dmg

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: App.dmg
          path: build/App.dmg

      - name: Clean up keychain
        if: always()
        run: security delete-keychain build.keychain

14. Gotchas

1. xcodebuild export method strings drift across Xcode versions — confirm ExportOptions.plist method values against xcodebuild -help for the pinned Xcode before hardcoding in CI (§ 1.1).
2. codesign --deep applies one entitlements file to the whole tree — wrong for any bundle with an XPC service needing narrower entitlements than the host app; sign inside-out manually instead (§ 3, full order in reference/distribution.md § 4).
3. set-key-partition-list is required on CI keychains — without it, codesign/notarytool hang waiting for a GUI keychain-access prompt that doesn't exist on a headless runner.
4. Staple the artifact you actually ship — stapling only the inner .app before zipping/DMG-wrapping still works for Gatekeeper's on-open check, but stapling the outer .dmg/.pkg additionally allows offline validation before the user opens it (reference/distribution.md § 5).
5. atos/symbolicatecrash need a matching dSYM UUID — dwarfdump --uuid on the dSYM must equal the crash report's binary UUID, or output is silently wrong, not an error.
6. install_name_tool invalidates the existing signature — always re-sign after mutating load commands.
7. xcresulttool's Xcode 16 schema break — pin parsers to the CI Xcode version or use --legacy.
8. App-specific password, not account password — notarytool/store-credentials require a per-app password generated at appleid.apple.com; the account's primary password will not authenticate.

Sources

• Distributing command-line tools outside the Mac App Store / Notarizing macOS software | Apple Developer Documentation (accessed 2026-07)
• NOTARYTOOL(1) man page (accessed 2026-07)
• Xcode Help — xcodebuild reference
• codesign man page — Apple Developer / macOS manpages (Code Signing In Depth, cross-reference against current man codesign on the CI runner's macOS version)
• Packaging and distributing software (pkgbuild/productbuild) | Apple Developer Documentation
• Cross-reference: reference/distribution.md (channel decision, signing-order narrative, Sparkle/App-Store flow), reference/sandbox-entitlements.md (entitlement catalog codesign --entitlements inspects), reference/xpc-helpers.md (§ 7 debugging commands for embedded XPC services), reference/xcrun-cli.md (iOS/simulator counterpart — simctl/devicectl)