How to Use the vphone-cli Command-Line Interface: Complete Guide

vphone-cli is a Swift-based command-line tool that orchestrates the complete lifecycle of virtual iPhones on macOS using Apple’s Virtualization.framework, exposing sub-commands for VM management, firmware patching, DFU restore, and system boot.

The vphone-cli repository (Lakr233/vphone-cli) provides a thin but powerful CLI wrapper around the VPhoneCore and FirmwarePatcher libraries. It enables developers to automate the provisioning of virtual iOS devices from shell scripts or CI pipelines on Apple Silicon Macs running macOS 15 or later.

Architecture and Command Registration

The application entry point resides in VPhoneCLI.swift, where the top-level command struct conforms to Apple’s ParsableCommand protocol.

// VPhoneCLI.swift (simplified structure)
@main
struct VPhoneCLI: ParsableCommand {
    static var configuration = CommandConfiguration(
        commandName: "vphone-cli",
        subcommands: [VPhoneBootCLI.self, PatchFirmwareCLI.self, ...]
    )
}

The CLI parses the first argument to determine which sub-command to execute, defaulting to boot when no sub-command is specified. Each sub-command is implemented as a separate ParsableCommand type that constructs configuration objects and delegates heavy operations to underlying Swift libraries.

Essential Sub-Commands

The interface exposes eight primary sub-commands, each targeting a specific stage of the virtual iPhone pipeline.

VM Management (vm)

The vm sub-command, implemented in VPhoneVMCLI.swift, handles bundle lifecycle operations. Use it to create, list, clone, export, import, and launch virtual machine bundles.

Key operations include:

• vm create <name> -V <variant> – Generates a new VM bundle and automatically runs the full firmware pipeline.
• vm launch <name> – Boots the VM with a graphical window using VPhoneVirtualMachine.
• vm list --json – Outputs machine-readable inventory of all available VMs.

Firmware Patching (patch-firmware)

The patch-firmware sub-command triggers the FirmwarePipeline engine defined in the FirmwarePatcher package.

vphone-cli patch-firmware <vm-name> --variant jb --force-exc-guard

This command processes the VM directory against a selected variant (less, regular, dev, jb, or exp), applying the 113-patch boot chain. Flags like --no-binpack or --force-exc-guard modify pipeline behavior as implemented in PatchFirmwareCLI.swift.

Component-Level Patching (patch-component)

For granular control, patch-component targets individual firmware payloads such as TXM, kernel base, or JB kernel.

vphone-cli patch-component \
    --component kernel-base \
    -i /path/to/kernelcache.im4p \
    -o /tmp/kernelpatched.bin \
    --records-out /tmp/records.json

This functionality resides in PatchComponentCLI.swift and produces JSON records documenting the transformation.

Direct Boot (boot)

The boot sub-command, defined in VPhoneBootCLI.swift, launches a VM directly from a manifest plist without requiring prior vm registration. It resolves the manifest into VPhoneVirtualMachine.Options—a configuration struct encapsulating CPU count, memory allocation, disk paths, NVRAM variables, and screen settings—then initializes the VPhoneVirtualMachine wrapper around Apple’s VZVirtualMachine.

Firmware Workflow (fw)

The fw command provides a high-level wrapper that orchestrates IPSW preparation and patching. It sequences fw prepare (downloading and merging IPSWs) followed by fw patch (invoking the firmware pipeline), effectively automating the manual steps required before the first boot.

Restore and Custom Firmware (restore, cfw)

• restore – Implements the DFU restore workflow in VPhoneRestoreCommand.swift. Supports operations like --get-shsh for fetching SHSH blobs before performing the actual DFU restore.
• cfw – Handles custom firmware installation via VPhoneCFWCommand.swift, mounting the VM disk on the host and injecting the modified firmware image.

Environment Setup (setup)

The setup sub-command, implemented as VPhoneSetupCommand, provides helpers for initial environment preparation, ensuring that host dependencies and directory structures are correctly configured before creating the first VM.

Practical Usage Examples

Quick-Start: Create and Launch

For rapid prototyping, create a jailbreak-variant VM and launch it in two commands:

vphone-cli vm create myphone -V jb
vphone-cli vm launch myphone

Manual Step-by-Step Pipeline

When debugging or customizing individual stages, execute the pipeline manually:

# Initialize empty bundle

vphone-cli vm new myphone

# Download and merge IPSWs

vphone-cli fw prepare myphone --iphone-version 26.1

# Apply firmware patches

vphone-cli fw patch myphone --variant jb

# Boot into DFU mode (background)

vphone-cli vm launch myphone --dfu &

# Fetch SHSH blobs and restore

vphone-cli restore myphone --get-shsh
vphone-cli restore myphone

# Stop DFU boot and install CFW

vphone-cli vm stop myphone
vphone-cli cfw install myphone --variant jb

# First normal boot

vphone-cli vm launch myphone

Automation and Scripting

List all VMs as JSON for external tooling:

vphone-cli vm list --json

For programmatic control, interact with the host-control socket located at <bundle>/vphone.sock, which accepts commands from utilities like vphone-mcp.

Core Implementation Details

The CLI delegates system virtualization to two primary types:

• VPhoneVirtualMachine.Options – Parsed from the manifest file in VPhoneBootCLI.run(), this struct defines the virtual hardware profile including CPU cores, RAM, storage attachments, and display parameters.
• FirmwarePipeline – The patching engine invoked by both patch-firmware and patch-component, handling cryptographic transformations and boot chain modifications.

These components isolate platform-specific logic from the argument-parsing layer, ensuring the CLI remains a thin wrapper that is easy to script and maintain.

Summary

• vphone-cli provides a ParsableCommand-based interface defined in VPhoneCLI.swift for managing virtual iPhones.
• Use vm create and vm launch for rapid provisioning, or vm new followed by fw commands for manual control.
• Apply firmware modifications via patch-firmware (full pipeline) or patch-component (single payload), both utilizing the FirmwarePipeline engine.
• Execute DFU restores with restore and install custom firmware using cfw before final boot.
• All VM configuration flows through VPhoneVirtualMachine.Options, while the actual virtualization relies on VPhoneVirtualMachine wrapping Apple's VZVirtualMachine.

Frequently Asked Questions

What are the system requirements for running vphone-cli?

The tool requires macOS 15 or later running on Apple Silicon hardware. It depends on Apple’s Virtualization.framework, which is only available on modern ARM64 Macs. The CLI itself is written in Swift and compiles with the Swift Package Manager.

How do I create a VM without automatically running the firmware pipeline?

Use the vm new sub-command instead of vm create. The new command initializes an empty bundle without invoking the firmware preparation or patching stages, allowing you to manually run fw prepare and fw patch with custom flags later.

Where does vphone-cli store VM configuration and sockets?

Each VM is a bundle directory containing a manifest plist, disk images, and firmware payloads. The CLI also creates a Unix domain socket at <bundle-path>/vphone.sock for host-control operations, enabling external automation tools to send commands to a running or stopped VM.

Can I automate vphone-cli from CI/CD pipelines?

Yes. The CLI is designed for scripting: use --json flags (e.g., vm list --json) for machine-readable output, and control the boot process via --dfu and backgrounding operators. The thin architecture separates argument parsing from execution logic, making it stable for unattended automation in VPhoneBootCLI.swift and VPhoneVMCLI.swift.

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