# How to Report a Bug in vphone-cli: A Complete Guide for macOS Virtualization

> Encounter a bug in vphone-cli on macOS? Learn how to report it effectively by providing essential system details, reproduction steps, and logs for a quicker resolution. Make your bug report count!

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

---

**To report a bug in vphone-cli, collect your macOS version, hardware model, Swift version, and the exact commit hash from [`VPhoneBuildInfo.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBuildInfo.swift), then provide numbered reproduction steps, console output or crash logs from [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift), and the guest daemon response from [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) before opening a GitHub issue.**

vphone-cli is a macOS-only command-line tool that boots a virtual iPhone using Apple's Virtualization.framework. Because the project spans host-side Swift UI, VM configuration, and guest-side daemon communication via vsock, effective bug reports must include specific diagnostic details from multiple subsystems to help maintainers reproduce and fix issues quickly.

## Essential Information for a High-Quality Bug Report

### Environment and Version Details

Since vphone-cli requires macOS 15+ with SIP and AMFI disabled, your report must specify your exact platform configuration. Include your macOS version (e.g., 15.1), Mac hardware model, Swift version from `swift --version`, and the exact vphone-cli build identifier. You can retrieve the commit hash programmatically using the build-time constant in [`VPhoneBuildInfo.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBuildInfo.swift):

```swift
import VPhoneBuildInfo

print("vphone-cli version: \(VPhoneBuildInfo.commitHash)")

```

Alternatively, run `git rev-parse HEAD` in the repository root to identify the source tree that produced your binary.

### Step-by-Step Reproduction

Provide a concise, numbered list that reproduces the problem from a fresh checkout. For example:

1. Clone the repository and run `make setup_venv && make build`
2. Execute `./vphone-cli boot` with any custom flags
3. Describe the specific action that triggers the failure

This allows maintainers to verify the bug using the same entry points defined in [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift).

### Observed vs Expected Behavior

Clearly state what happened versus what should have happened. Attach console output, crash logs, or UI screenshots. If the application crashed, include the stack trace. If the VM failed to boot, note the exact error message from [`VPhoneError.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneError.swift).

### Configuration and Logs

Document any non-default settings from `VPhoneVirtualMachine.Options` or hardware model overrides in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift). Include relevant logs from three critical sources:

- **Host-side logs**: Written by the `NSApplication` delegate in [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift)
- **VM logs**: Events from `VZVirtualMachine` handled in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift)
- **Guest-side logs**: Output from `vphoned` inside the VM, accessible via the vsock client in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift)

Use this snippet to extract host-side logs:

```swift
import VPhoneAppDelegate

class Logger {
    static func dumpLog() -> String {
        let logPath = "\(NSHomeDirectory())/Library/Logs/vphone-cli.log"
        return (try? String(contentsOfFile: logPath)) ?? "No log found"
    }
}

print(Logger.dumpLog())

```

## Key Source Files Referenced in Bug Reports

When describing your issue, reference these specific files from the repository to help maintainers locate the problem:

- **[`sources/vphone-cli/VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneAppDelegate.swift)**: Sets up the `NSApplication`, handles termination, and writes host logs
- **[`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift)**: Configures and controls the `VZVirtualMachine` instance
- **[`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift)**: Host-side vsock client that communicates with the guest daemon
- **[`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift)**: Parses command-line arguments and launches workflows
- **[`sources/vphone-cli/VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneHardwareModel.swift)**: Defines the virtual hardware model (PV = 3) via the Dynamic library
- **[`sources/vphone-cli/VPhoneError.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneError.swift)**: Central error enum used throughout the codebase

## How to Submit Your Bug Report

Once you have gathered the environment details, reproduction steps, and logs:

1. Navigate to the **Issues** tab of the Lakr233/vphone-cli repository
2. Click **New issue** and select the *Bug report* template
3. Fill in the sections with your collected data, attaching log files or screenshots as needed
4. Submit the issue

Maintainers will triage the report, attempt reproduction using the steps provided, and may request additional information such as a minimal test case or core dump.

## Summary

- **vphone-cli** requires macOS 15+ with SIP/AMFI disabled, so always include your exact macOS version and hardware model
- Capture the commit hash from [`VPhoneBuildInfo.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneBuildInfo.swift) using `git rev-parse HEAD` to identify your build
- Structure your report with numbered reproduction steps starting from `make build`
- Include logs from [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift) (host), [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (VM), and [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) (guest communication)
- Reference specific source files like [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift) or [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) when describing configuration issues
- Submit via GitHub Issues using the bug report template

## Frequently Asked Questions

### What macOS versions are supported by vphone-cli?

vphone-cli requires macOS 15 or later because it relies on specific APIs within Apple's Virtualization.framework that are only available in recent versions. Additionally, System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI) must be disabled for the virtual machine to boot properly.

### How do I capture logs from the guest daemon?

The guest daemon `vphoned` runs inside the virtualized iPhone environment. You can query its status and retrieve logs using the vsock client implemented in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift):

```swift
import VPhoneControl

VPhoneControl.shared.send(command: "ping") { response in
    print("Guest daemon replied: \(response)")
}

```

### Which log files are most important for VM boot failures?

For boot-related issues, prioritize logs from [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) which handles `VZVirtualMachine` events, and [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift) which captures host-side initialization errors. The interaction between these two components typically reveals whether the failure occurs during VM configuration or guest handoff.

### How do I list available VM options when reporting configuration bugs?

You can print the default VM configuration to verify if custom settings in `VPhoneVirtualMachine.Options` are causing the issue:

```swift
import VPhoneVirtualMachine

let options = VPhoneVirtualMachine.Options.default
print("Default VM options: \(options)")

```

This output helps maintainers determine if non-standard hardware models defined in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) or modified command-line flags from [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift) are contributing to the bug.