# vphone-cli Commands: Complete Guide to Booting and Managing Virtual iPhones > Master vphone-cli commands to boot virtual iPhones, patch firmware, and manage VM bundles. This comprehensive guide covers essential CLI operations for developers. - Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli) - Tags: how-to-guide - Published: 2026-09-11 --- **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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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: ```bash vphone-cli boot --config ./config.plist ``` Boot in DFU mode for headless firmware operations: ```bash vphone-cli boot --config ./config.plist --dfu ``` Apply the regular firmware variant to a VM directory: ```bash vphone-cli patch-firmware -d /path/to/vm-dir ``` Patch with jailbreak variant and enable Frida relaxations: ```bash vphone-cli patch-firmware -d /path/to/vm-dir -V jb --frida ``` Patch a single TXM bootloader component: ```bash vphone-cli patch-component \ --component txm \ -i /tmp/kernelcache.im4p \ -o /tmp/kernelcache.patched.im4p ``` List all VM bundles in the default library: ```bash vphone-cli vm list ``` Create a new VM with specific resource allocation: ```bash vphone-cli vm new myVM --cpu 4 --memory 4096 --disk-size 32 ``` Configure a VM to use bridged networking: ```bash vphone-cli vm config myVM --network bridged ``` Launch a VM with the virtual iPhone display window: ```bash 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMCLI.swift), while [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.