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

> Learn how to update vphone-cli to the latest version with this complete build guide. Follow simple steps to pull commits, update submodules, and rebuild the Swift binary.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift) manifest
- **Make** and **Homebrew** (used by [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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`.

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh), this updates Homebrew packages, rebuilds submodule binaries from source, and synchronizes the Python virtual environment in `.venv/` against [`requirements.txt`](https://github.com/Lakr233/vphone-cli/blob/main/requirements.txt).

```bash
make setup_tools

```

This target (defined at lines 46‑70 in `Makefile`) detects changes to [`requirements.txt`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneBuildInfo.swift), executes `swift build -c release`, and signs the output with `sources/vphone.entitlements`.

```bash
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:

```bash
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`)

```bash
make cfw_install_jb

```

This invokes [`scripts/cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
#!/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.