Installation Guide

Specchio requires a few one-time setup steps before first use. This guide walks you through each step.

Table of Contents

1. System Requirements
2. Install Xcode
3. Accept the Xcode License
4. Install iOS Platform SDK
5. Create an Apple Development Certificate
6. Verify Everything is Ready

---

System Requirements

Before you begin, ensure your Mac meets these requirements:

• macOS: Sonoma (14.0) or later
• Disk Space: At least 20 GB free (for Xcode)
• Internet Connection: Required for downloading Xcode and components
• Apple ID: Free Apple ID required for certificate creation

Check your macOS version:

sw_vers

You should see ProductVersion: 14.x or higher.

---

Install Xcode

Xcode is Apple's development tools package. Specchio uses it to communicate with your iPhone.

Option 1: Install from App Store (Recommended)

1. Open App Store on your Mac
2. Search for Xcode
3. Click Get or Download (free, approximately 12-15 GB)
4. Wait for the download to complete (this can take 30-60 minutes depending on your internet)

Option 2: Install from Terminal

If you prefer command-line installation:

# Search for Xcode
mas search xcode

# Install Xcode (note the app ID)
mas install 497799835

This requires the mas CLI tool. If you don't have it, use the App Store instead.

Verify Xcode Installation

After installation, verify Xcode is installed:

# Check if Xcode.app exists
ls -la /Applications/Xcode.app

# Check Xcode version
xcodebuild -version

Expected output:

Xcode 16.0
Build version 16A242d

---

Accept the Xcode License

Before using Xcode, you must accept its license agreement.

Option 1: Launch Xcode (Recommended)

1. Open Xcode from Applications
2. Click Agree to accept the license terms
3. Wait for Xcode to install additional components
4. Quit Xcode once it opens

Option 2: Accept via Terminal

sudo xcodebuild -license accept

You'll be prompted for your Mac password. Type it (it won't appear on screen) and press Enter.

Verify License is Accepted

xcodebuild -checkFirstLaunchStatus

If you see Xcode has already been accepted. or no errors, you're all set.

---

Install iOS Platform SDK

Specchio needs the iOS platform SDK to communicate with your iPhone.

Option 1: Install via Xcode (Recommended)

1. Open Xcode
2. Go to Xcode → Settings (or Preferences on older versions)
3. Click the Platforms tab
4. Find iOS in the list
5. Click Get or Download next to it (approximately 6 GB)
6. Wait for the download to complete

Option 2: Install via Terminal

# List available platforms
xcodebuild -showsdks

# If iOS SDK is not shown, install it via Xcode Settings
open "xcode://settings"

Verify iOS SDK Installation

xcodebuild -showsdks

Look for iOS ... in the output. Example:

iOS SDKs:
    iOS 18.0          	-sdk iphoneos18.0

---

Create an Apple Development Certificate

Specchio needs a code signing certificate to install components on your iPhone.

Prerequisites

• You must have a free Apple ID
• If you don't have one, create one at https://appleid.apple.com

Step-by-Step Certificate Creation

1. Open Xcode

2. Go to Xcode → Settings (or Preferences)

3. Click the Accounts tab

4. Click the + button in the bottom left

5. Select Apple ID from the dropdown

6. Sign in with your Apple ID and password

7. Your Apple ID now appears in the accounts list

8. With your Apple ID selected, click Manage Certificates...

9. Click the + button

10. Select Apple Development from the dropdown

11. The certificate will be created automatically

Verify Certificate Creation

# Find your signing identity
security find-identity -v -p codesigning | grep "Apple Development"

Expected output (one or more lines):

1) 0123456789ABCDEF0123456789ABCDEF01234567 "Apple Development: your.email@example.com (ABCDEFGHIJ)"

If you see this, your certificate is ready!

---

Verify Everything is Ready

Before launching Specchio, run this quick check:

#!/bin/bash
echo "Checking Specchio prerequisites..."
echo ""

# Check Xcode
echo "1. Checking Xcode installation..."
if [ -d "/Applications/Xcode.app" ]; then
    echo "   ✅ Xcode.app found"
    xcodebuild -version | sed 's/^/   /'
else
    echo "   ❌ Xcode.app not found"
fi
echo ""

# Check Xcode license
echo "2. Checking Xcode license..."
if xcodebuild -checkFirstLaunchStatus 2>&1 | grep -q "already been accepted"; then
    echo "   ✅ Xcode license accepted"
else
    echo "   ❌ Xcode license not accepted"
    echo "   Run: sudo xcodebuild -license accept"
fi
echo ""

# Check iOS SDK
echo "3. Checking iOS Platform SDK..."
if xcodebuild -showsdks | grep -q "iphoneos"; then
    echo "   ✅ iOS SDK installed"
    xcodebuild -showsdks | grep "iphoneos" | head -1 | sed 's/^/   /'
else
    echo "   ❌ iOS SDK not found"
    echo "   Install via: Xcode → Settings → Platforms → iOS → Get"
fi
echo ""

# Check certificate
echo "4. Checking Apple Development certificate..."
if security find-identity -v -p codesigning 2>/dev/null | grep -q "Apple Development"; then
    echo "   ✅ Apple Development certificate found"
    security find-identity -v -p codesigning | grep "Apple Development" | head -1 | sed 's/^/   /'
else
    echo "   ❌ No Apple Development certificate found"
    echo "   Create via: Xcode → Settings → Accounts → Manage Certificates → + → Apple Development"
fi
echo ""

echo "Check complete!"

Save this script as check-specchio-prerequisites.sh, make it executable, and run it:

chmod +x check-specchio-prerequisites.sh
./check-specchio-prerequisites.sh

---

What's Next?

Once all prerequisites are met:

1. Continue to Device Setup to prepare your iPhone
2. Then read First Connection to connect your devices

---

Troubleshooting

Xcode installation fails

Problem: App Store shows an error during download.

Solutions:

• Ensure you have at least 20 GB of free disk space
• Try restarting your Mac and downloading again
• Check your internet connection
• If using a VPN, try disabling it during download

Can't accept license via Terminal

Problem: sudo xcodebuild -license accept shows an error.

Solutions:

• Make sure you're typing your Mac password correctly
• Try opening Xcode once and accepting through the UI
• Check that Xcode.app is in /Applications/

Certificate creation fails

Problem: "Manage Certificates" button is greyed out or certificate creation fails.

Solutions:

• Make sure you're signed in with an Apple ID in Xcode → Settings → Accounts
• Try removing and re-adding your Apple ID
• Check that you have a stable internet connection
• Ensure Two-Factor Authentication is enabled on your Apple ID

For more help, see the Troubleshooting section.