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

> Master vphone-cli, the Swift command-line tool for managing virtual iPhones on macOS. Control VM lifecycle, firmware, DFU restore, and boot with this comprehensive guide.

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

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift), where the top-level command struct conforms to Apple’s `ParsableCommand` protocol.

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

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

### Component-Level Patching (patch-component)

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

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/PatchComponentCLI.swift) and produces JSON records documenting the transformation.

### Direct Boot (boot)

The `boot` sub-command, defined in [`VPhoneBootCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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:

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

```bash

# 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:

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBootCLI.swift) and [`VPhoneVMCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMCLI.swift).