vphone-cli Commands: Complete Guide to Booting and Managing Virtual iPhones

vphone-cli commands enable you to boot virtual iPhones, patch iOS firmware, and manage VM bundles through a Swift-based CLI built on Apple's ArgumentParser library.

vphone-cli is a Swift-based command-line tool developed in the Lakr233/vphone-cli repository that provides comprehensive control over virtual iPhone environments. The vphone-cli commands are organized into logical groups including boot operations, firmware patching, and VM lifecycle management, all defined as sub-commands in sources/vphone-cli/VPhoneCLI.swift. Each command group leverages Apple's ArgumentParser framework, ensuring consistent flag syntax and built-in --help documentation across the entire interface.

Core vphone-cli Command Groups

The root parser in VPhoneCLI.swift defines several top-level command groups that handle distinct aspects of virtual iPhone management.

Boot Operations

The boot command creates and starts a PV = 3 virtual iPhone from a manifest plist configuration file. This command supports both standard boot sequences and specialized modes for development.

• Use --config to specify the path to your manifest plist file
• Add --dfu to boot in DFU (Device Firmware Update) mode for headless operations
• Boot logic is implemented within VPhoneCLI.swift via the embedded VPhoneBootCLI component

Firmware Patching

vphone-cli provides two distinct approaches to firmware modification through the patch commands defined in VPhoneCLI.swift.

patch-firmware applies the full Swift patch pipeline to an entire VM directory. This command accepts:

• -d flag for the VM directory path
• -V flag to specify the variant: regular, dev, or jb (jailbreak)
• --frida flag to enable Frida-specific relaxations for dynamic instrumentation

patch-component performs surgical modifications on individual firmware components:

• --component accepts txm, kernel-base, or kernel-jb targets
• -i and -o flags define input and output IM4P file paths
• Utilizes TXMPatcher, KernelPatcher, and KernelJBPatcher classes internally

VM Bundle Management

The vm command group, implemented in sources/vphone-cli/VPhoneVMCLI.swift, provides comprehensive lifecycle management for virtual machine bundles stored in the default library (~/.vphone/VMs).

Available sub-commands include:

• list – Display all VM bundles in the library
• new – Create a VM with --cpu, --memory, and --disk-size parameters
• config – Modify VM settings such as --network bridged
• info, rename, delete, clone, export, import, launch, stop, create

System Setup and Utilities

Additional command groups handle specialized operations:

• setup – Automates initial machine setup and dependency installation (see sources/vphone-cli/VPhoneSetupCommand.swift)
• restore – Provides restore-related helpers via VPhoneRestoreCLI
• cfw – Installs custom firmware on host-mounted images via VPhoneCFWCommand
• fw – Exposes low-level firmware utilities through VPhoneFWCommand

Practical vphone-cli Usage Examples

The following examples demonstrate common workflows using the vphone-cli commands. All flags support the --help option for detailed parameter discovery.

Boot a virtual iPhone from a configuration manifest:

vphone-cli boot --config ./config.plist

Boot in DFU mode for headless firmware operations:

vphone-cli boot --config ./config.plist --dfu

Apply the regular firmware variant to a VM directory:

vphone-cli patch-firmware -d /path/to/vm-dir

Patch with jailbreak variant and enable Frida relaxations:

vphone-cli patch-firmware -d /path/to/vm-dir -V jb --frida

Patch a single TXM bootloader component:

vphone-cli patch-component \
    --component txm \
    -i /tmp/kernelcache.im4p \
    -o /tmp/kernelcache.patched.im4p

List all VM bundles in the default library:

vphone-cli vm list

Create a new VM with specific resource allocation:

vphone-cli vm new myVM --cpu 4 --memory 4096 --disk-size 32

Configure a VM to use bridged networking:

vphone-cli vm config myVM --network bridged

Launch a VM with the virtual iPhone display window:

vphone-cli vm launch myVM

Source File Architecture

The command-line interface is structured across specialized Swift files within the sources/vphone-cli/ directory. VPhoneCLI.swift serves as the root command definition, embedding VPhoneBootCLI, PatchFirmwareCLI, and PatchComponentCLI for firmware operations. The vm sub-command group resides in VPhoneVMCLI.swift, while VPhoneVirtualMachine.swift handles the core VM configuration and lifecycle logic used by both boot and vm launch commands. Environment setup functionality is isolated in VPhoneSetupCommand.swift. Each file defines ParsableCommand structs conforming to ArgumentParser protocols, enabling the modular command structure.

Summary

• vphone-cli manages virtual iPhones through eight primary command groups: boot, patch-firmware, patch-component, vm, setup, restore, cfw, and fw.
• The boot command initializes PV=3 virtual iPhones from manifest plists with optional DFU mode support.
• Firmware patching supports both full-directory pipelines (patch-firmware) and single-component modifications (patch-component) for TXM, kernel-base, and kernel-JB targets.
• VM management commands in the vm group handle bundle creation, configuration, networking, and lifecycle operations through VPhoneVMCLI.swift.
• All commands support ArgumentParser's standard --help flags for interactive documentation.

Frequently Asked Questions

How do I boot a virtual iPhone in DFU mode using vphone-cli?

Append the --dfu flag to the boot command when specifying your configuration plist. This initiates a headless boot sequence without displaying the virtual iPhone window, which is essential for automated firmware flashing workflows.

What is the difference between patch-firmware and patch-component commands?

The patch-firmware command applies comprehensive patches to an entire VM directory using the FirmwarePipeline class, supporting variants like regular, dev, and jb. In contrast, patch-component targets individual firmware elements using specialized patchers such as TXMPatcher or KernelPatcher for surgical modifications to specific IM4P files.

Where does vphone-cli store VM bundles by default?

VM bundles are stored in the default library directory at ~/.vphone/VMs unless explicitly configured otherwise. The vphone-cli vm list command scans this location to display available virtual machines.

How can I view all available options for a specific vphone-cli command?

Append --help to any command or sub-command to display comprehensive documentation. For example, vphone-cli vm new --help reveals all available flags for CPU cores, memory allocation, and disk sizing when creating new virtual machines.

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