# How to Use the Key Make Targets for vphone-cli: Complete Build and VM Management Guide

> Master vphone-cli's key make targets for effortless virtual iPhone build and VM management. Automate host setup, compilation, patching, booting, and restoration with this comprehensive guide.

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

---

**The vphone-cli Makefile defines 25+ automated targets that handle the full virtual iPhone lifecycle, from host setup and binary compilation to firmware patching, VM booting, and iOS restoration.**

This article breaks down every essential **make target for vphone-cli** based on the actual source code in [Lakr233/vphone-cli](https://github.com/Lakr233/vphone-cli). Whether you're building the CLI for the first time or managing multiple VM snapshots, these targets eliminate manual steps and ensure reproducible workflows.

---

## Setup and Tooling Targets

### setup_machine: One-Step Full Environment Setup

The `setup_machine` target (lines 48–68 in `Makefile`) performs complete host preparation and first-boot of a virtual iPhone. It accepts optional flags for **JB/DEV/EXP/LESS modes** and handles sudo password injection automatically.

```bash
make setup_machine

```

### setup_tools: Install Host Dependencies

The `setup_tools` target (lines 70–73) invokes [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) to install:

- Homebrew packages
- trustcache and insert_dylib tools
- Python virtual environment
- pymobiledevice3

```bash
make setup_tools

```

Run this once per development machine before any build or VM operations.

---

## Build Targets for vphone-cli Components

### build: Compile the Signed CLI Binary

The `build` target (lines 5–27) compiles the release configuration and **embeds the current Git short hash** into [`VPhoneBuildInfo.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBuildInfo.swift) for version tracking.

```bash
make build

```

Source: [`sources/vphone-cli/Package.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/Package.swift) drives the underlying `swift build` commands.

### bundle: Create macOS App Package

The `bundle` target (lines 27–37) packages the binary into a signed `.app` bundle with proper entitlements and resource copying.

### vphoned: Cross-Compile the Guest Daemon

The `vphoned` target (lines 38–51) cross-compiles the iOS arm64 daemon, signs it with `ldid`, and places it in the VM directory. This daemon enables advanced VM features during boot.

---

## VM Lifecycle Management Targets

### vm_new: Initialize a Fresh Virtual Machine

Creates `$(VM_DIR)` with a `config.plist` specifying **8 CPU cores, 8 GB RAM, and 64 GB disk** by default (lines 56–62). Source: [`scripts/vm_create.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/vm_create.sh).

```bash
make vm_new

```

### VM Snapshot Targets

| Target | Purpose | Line Range |
|--------|---------|------------|
| `vm_backup` | Create named backup | 63–68 |
| `vm_restore` | Restore from named backup | 69–72 |
| `vm_switch` | Swap between backups atomically | 73–75 |
| `vm_list` | Display all stored backups | 76–78 |

Usage example:

```bash
make vm_backup NAME=pre-jb-test
make vm_restore NAME=pre-jb-test
make vm_switch NAME=stable-release

```

---

## Firmware and Boot Targets

### fw_prepare: Download and Extract IPSWs

Downloads required iOS firmware files and merges **cloudOS components** into the VM directory (lines 45–51).

### Firmware Patch Variants

The `fw_patch*` family runs the Swift-based patching pipeline through [`scripts/patchers/cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py):

- `fw_patch` — Standard variant
- `fw_patch_less` — Minimal compatibility mode
- `fw_patch_dev` — Developer features enabled
- `fw_patch_jb` — Jailbreak patches included
- `fw_patch_exp` — Experimental features

```bash
make fw_patch_jb  # Apply jailbreak patches

```

### Boot Targets

| Target | Behavior | Lines |
|--------|----------|-------|
| `boot` | Full-featured boot with vphoned | 28–33 |
| `boot_less` | Patch-less mode (no daemon) | 34–38 |
| `boot_dfu` | Direct DFU mode entry | 39–42 |

Use `boot_less` when the `vphoned` daemon is omitted or incompatible with your target iOS version.

---

## Testing and Validation Targets

### Automated Test Suites

- `test_jb_patches` (lines 82–90): Validate jailbreak kernel patches
- `test_fw_patches` (lines 91–100): Full firmware-patch pipeline verification

```bash
make test_fw_patches  # Run before committing changes

```

---

## iOS Restore Targets

### restore_get_shsh: Fetch Signing Tickets

Uses **pymobiledevice3** to retrieve SHSH blobs from Apple's servers (lines 104–112).

### Restore Operations

| Target | Method | Lines |
|--------|--------|-------|
| `restore` | Online restore with live SHSH | 113–118 |
| `restore_offline` | Cached SHSH, no server contact | 119–124 |

Offline restore requires a previously saved blob from `restore_get_shsh`.

---

## Custom Firmware (CFW) Installation Targets

Install host-mount CFW for specific variants:

| Target | Description | Lines |
|--------|-------------|-------|
| `cfw_install` | Standard CFW | 126–130 |
| `cfw_install_dev` | Developer variant | 131 |
| `cfw_install_jb` | Jailbreak variant | 132 |
| `cfw_install_exp` | Experimental variant | 133 |
| `cfw_install_host` | Underlying sudo driver | 134–138 |

Example workflow:

```bash
make fw_patch_jb
make cfw_install_jb
make boot

```

---

## Complete vphone-cli Workflow Example

```bash

# 1. Install all host tools (run once)

make setup_tools

# 2. Build and bundle the CLI

make build && make bundle

# 3. Create VM and prepare firmware

make vm_new
make fw_prepare

# 4. Patch and install jailbreak CFW

make fw_patch_jb
make cfw_install_jb

# 5. Boot with full features

make boot

# 6. Create backup before experiments

make vm_backup NAME=jb-working

# 7. Test patches and restore if needed

make test_jb_patches
make vm_restore NAME=jb-working

```

---

## Summary

- **vphone-cli make targets** consolidate 25+ operations into single commands, from `setup_machine` (full environment) to granular controls like `boot_dfu` or `cfw_install_exp`.
- The `Makefile` (main build script), [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/setup_tools.sh) (dependency installer), and [`scripts/patchers/cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py) (firmware patcher) form the core automation layer.
- VM snapshots (`vm_backup`, `vm_restore`, `vm_switch`) enable safe experimentation with jailbreak and experimental patches.
- All firmware patching and CFW installation support **five distinct variants**: default, less, dev, jb, and exp.
- Testing targets (`test_jb_patches`, `test_fw_patches`) validate changes before deployment to physical or virtual devices.

---

## Frequently Asked Questions

### What is the difference between `boot` and `boot_less` in vphone-cli?

`boot` launches the VM with the full `vphoned` daemon, enabling advanced features like host-guest communication and dynamic patching. `boot_less` (lines 34–38) starts in **patch-less compatibility mode** using `--variant less`, which bypasses the daemon entirely—useful when `vphoned` is incompatible with your target iOS version or when debugging baseline behavior.

### How do I create and restore VM backups using make targets?

Run `make vm_backup NAME=your-label` to snapshot the current VM state to `$(VM_DIR)/backups/your-label`. Restore with `make vm_restore NAME=your-label` or atomically switch between backups using `make vm_switch NAME=another-label`. List all backups with `make vm_list`. These operations are implemented in `Makefile` lines 63–78.

### Which make target should I run first on a new machine?

Always start with **`make setup_tools`** followed by **`make build`**. The `setup_tools` target installs all host dependencies including Python tooling, code signing utilities, and submodules. Once built, `make setup_machine` can perform complete automated setup including first VM creation and boot if you prefer a single command.

### What do the firmware patch variants (jb, dev, exp, less) actually change?

Each `fw_patch_*` target passes a different `--variant` flag to [`scripts/patchers/cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py): **jb** applies jailbreak kernel patches; **dev** enables developer debugging features; **exp** activates experimental modifications; **less** minimizes patches for maximum compatibility. The matching `cfw_install_*` and `boot_*` targets must use the same variant for consistent behavior.