How to Update vphone‑cli to the Latest Version: Complete Build Guide

To update vphone‑cli, pull the latest commits and submodules with git pull --rebase && git submodule update --init --recursive, refresh the host toolchain via make setup_tools, and rebuild the signed Swift binary using make build.

vphone‑cli is a Swift‑based command‑line tool for managing iOS virtual machines, maintained in the open‑source repository Lakr233/vphone‑cli. Because the project embeds private iOS toolchains (libimobiledevice, trustcache) and compiles a code‑signed release binary, updating requires rebuilding the entire development environment—not just pulling source changes.

Prerequisites for Updating

Before starting, ensure you have:

• Git with submodule support (for .gitmodules dependencies)
• Xcode or Swift toolchain matching the Package.swift manifest
• Make and Homebrew (used by scripts/setup_tools.sh for dependency resolution)

Step‑by‑Step Update Procedure

The canonical update workflow follows the build orchestration defined in the root Makefile. Execute these phases in order to keep the host tooling, Swift binary, and optional Custom Firmware (CFW) synchronized.

Pull the Latest Source Code

Synchronize the repository and its submodules. The project vendors components like trustcache and insert_dylib under scripts/repos/, controlled by .gitmodules.

git pull --rebase
git submodule update --init --recursive

The --recursive flag ensures nested dependencies are refreshed, which is critical when upstream changes affect the dynamic injection toolchain used by the CLI.

Refresh the Development Environment

Run the setup target to idempotently reinstall host dependencies. According to scripts/setup_tools.sh, this updates Homebrew packages, rebuilds submodule binaries from source, and synchronizes the Python virtual environment in .venv/ against requirements.txt.

make setup_tools

This target (defined at lines 46‑70 in Makefile) detects changes to requirements.txt and automatically upgrades pymobiledevice3, capstone, and other Python helpers used for USB communication with virtual iOS devices.

Rebuild the Signed Swift Binary

Compile the release binary and apply private entitlements. The build target (lines 5‑22 in Makefile) writes the current Git hash into sources/VPhoneBuildInfo.swift, executes swift build -c release, and signs the output with sources/vphone.entitlements.

make build

The resulting binary includes the embedded build identifier and maintains valid code signatures required for amfidont integration and VM management commands.

(Optional) Re‑bundle the macOS Application

If you use the GUI boot flow or the amfidont helper, package the binary into a .app bundle:

make bundle

The bundle target (lines 27‑36) assembles the macOS application structure, ensuring the signed executable retains its entitlements when launched from Finder or via open.

(Optional) Update the Custom Firmware

When the update includes kernel patches or root filesystem changes, reinstall the CFW on the VM disk image. The Makefile provides four installation targets at lines 78‑99:

• make cfw_install – Standard firmware with base patches
• make cfw_install_dev – Development build with verbose kernel logging
• make cfw_install_jb – Jailbreak‑enabled firmware for unsigned code execution
• make cfw_install_exp – Experimental features (requires SPOOF_BUILD=1)

make cfw_install_jb

This invokes scripts/cfw_install_host.sh to mount the VM disk and atomically write the patched system image, preserving user data while updating the operating system stack.

Complete Automated Update Script

Combine all steps into a single bash routine for unattended updates:

#!/usr/bin/env bash
set -euo pipefail

# Sync source and submodules

git pull --rebase
git submodule update --init --recursive

# Refresh toolchain and Python environment

make setup_tools

# Build and sign the Swift binary

make build

# Package for GUI usage (optional)

make bundle

# Update jailbreak firmware (optional)

make cfw_install_jb

# Boot with the new version

make boot

Save this as update_vphone.sh, mark it executable with chmod +x, and run it from the repository root.

Troubleshooting Update Issues

Submodule merge conflicts: If git submodule update fails withmerge conflicts, manually reset the submodule to the upstream commit recorded in the main repository:

cd scripts/repos/trustcache
git reset --hard origin/main
cd -
git submodule update --init --recursive

Python environment drift: When pymobiledevice3 reports API errors after an update, force‑recreate the virtual environment:

rm -rf .venv
make setup_tools

Code‑signing failures: Ensure the entitlements file at sources/vphone.entitlements has not been modified, and that your signing certificate is valid in Keychain Access.

Summary

• Pull the latest code with git pull --rebase and git submodule update --init --recursive to fetch source and dependency changes.
• Refresh the host toolchain by running make setup_tools, which updates the Python venv and rebuilds submodule binaries like trustcache.
• Rebuild the signed CLI using make build, which compiles the Swift source and applies entitlements from sources/vphone.entitlements.
• Re‑bundle the macOS app with make bundle if you require GUI launching or amfidont support.
• Re‑install the CFW only when necessary via make cfw_install_<variant> (jb, dev, or exp) to update the VM’s operating system.
• Boot the VM with make boot to verify the updated binary and firmware.

Frequently Asked Questions

Do I need to reinstall the CFW every time I update vphone‑cli?

No. Reinstall the Custom Firmware only when the release notes indicate changes to scripts/cfw_install_host.sh, kernel patches, or root filesystem layouts. Routine CLI updates that modify only the Swift source require only make build to refresh the signed binary while preserving the existing VM disk image.

Why does make setup_tools reinstall Python packages?

The setup_tools target is idempotent; it compares the current .venv/ state against requirements.txt and upgrades packages like pymobiledevice3 and capstone when the manifest changes. This ensures the Python helpers remain compatible with the latest iOS debugging protocols without manual pip invocations.

How do I update only the Python environment without rebuilding Swift?

Activate the virtual environment and upgrade dependencies manually: source .venv/bin/activate && pip install -r requirements.txt --upgrade. Alternatively, running make setup_tools skips the Swift build phase and only refreshes the host tooling and Python venv, making it safe to run independently of make build.

What is the difference between the CFW variants (jb, dev, exp)?

The jb (jailbreak) variant patches the kernel to allow unsigned code execution and root access inside the VM. The dev variant adds verbose logging and debug symbols to assist core development. The exp (experimental) variant activates bleeding‑edge features that require the SPOOF_BUILD=1 environment variable, typically used for testing unmerged patches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}