Where Are vphone-cli Configuration Files Stored?

vphone-cli stores every virtual iPhone instance's settings in a Property List file named config.plist located inside the VM bundle directory, defaulting to ./config.plist in your current working directory.

vphone-cli is a command-line tool for managing virtual iPhone instances on macOS. According to the Lakr233/vphone-cli source code, the tool persists all VM hardware and system settings in a single manifest file that you can inspect, edit, and version control. Understanding exactly where vphone-cli configuration files are stored enables you to automate deployments, backup specific machine states, and manage multiple virtual devices efficiently.

Default Location of the config.plist File

By default, vphone-cli configuration files are stored as config.plist in the root of the VM bundle directory. This Property List (plist) file contains the complete hardware specification for your virtual iPhone, including the machine identifier, CPU count, memory allocation, screen resolution, network settings, and storage configuration.

Each virtual machine operates within its own bundle folder. When you run vphone-cli new, the tool creates this bundle in your current directory unless specified otherwise. The config.plist sits alongside other VM assets such as the disk image and NVRAM files, making the bundle self-contained and portable.

How the CLI Specifies the Configuration Path

The CLI entry point in VPhoneCLI.swift declares a --config option that allows you to override the default path. The Swift Argument Parser implementation accepts a URL value that gets passed directly to the virtual machine constructor.

@Option(name: .shortAndLong,
        help: "Path to VM manifest plist (config.plist). Required.")
var config: URL

let vm = VPhoneVirtualMachine(options: .init(configURL: config, ...))

When you omit the --config flag, the tool resolves to ./config.plist relative to your current working directory. This design ensures that each VM bundle maintains its own isolated configuration while giving you the flexibility to store manifests anywhere on your filesystem.

The Manifest Loading and Persistence Layer

The actual serialization logic lives in VPhoneVirtualMachineManifest.swift within the VPhoneCore module. This file defines the VPhoneVirtualMachineManifest type with two critical methods for managing vphone-cli configuration files:

public static func load(from url: URL) throws -> VPhoneVirtualMachineManifest
public func write(to url: URL) throws

The load(from:) method reads the plist from disk and deserializes it into a strongly-typed Swift structure, while write(to:) persists any modifications back to the specified URL. Error handling uses Swift's throws mechanism to catch file system or parsing issues during I/O operations.

In VPhoneVirtualMachine.swift, the VM initialization code stores the configuration path in a configURL property and immediately loads the manifest:

var configURL: URL
var manifest = try VPhoneVirtualMachineManifest.load(from: options.configURL)

This architecture decouples the CLI interface from the persistence layer, allowing both the command-line tool and Swift programmatic APIs to operate on the same configuration file format.

Practical Examples for Managing Config Files

You can interact with vphone-cli configuration files through both the command-line interface and Swift code.

Command-Line Operations

# Create a new VM bundle with default config.plist

vphone-cli new

# Inspect the manifest contents

vphone-cli info --config ./config.plist

# Modify specific hardware parameters

vphone-cli config --config ./config.plist --memory 8G

Programmatic Modification

import Foundation
import VPhoneCore

// Load an existing manifest
let url = URL(fileURLWithPath: "./config.plist")
let manifest = try VPhoneVirtualMachineManifest.load(from: url)

// Update memory allocation to 8 GiB
let updated = manifest.updating(memorySize: 8 * 1024 * 1024 * 1024)
try updated.write(to: url)

These examples demonstrate how the --config flag controls which file path the CLI targets, and how the Swift API provides type-safe methods for updating hardware specifications before writing them back to disk.

Summary

• vphone-cli configuration files are single config.plist Property List files stored inside each VM bundle directory.
• The default location is ./config.plist relative to the current working directory, though you can override this using the --config flag.
• Configuration persistence is handled by VPhoneVirtualMachineManifest.swift, which provides load(from:) and write(to:) methods for reading and writing plist data.
• The VPhoneVirtualMachine.swift file maintains a configURL property that references the active configuration file path throughout the VM lifecycle.
• Both CLI commands and Swift programmatic APIs can inspect and modify these files to adjust CPU, memory, storage, and network settings.

Frequently Asked Questions

Where is the vphone-cli configuration file located by default?

By default, vphone-cli looks for a file named config.plist in the current working directory where you execute the command. When you create a new VM with vphone-cli new, the tool generates this file alongside the virtual disk image and other bundle assets in that location.

Can I store the vphone-cli config file in a custom directory?

Yes. Use the --config option followed by a path to specify an alternative location for the manifest file. For example, vphone-cli info --config /path/to/custom/config.plist reads the configuration from that specific URL instead of the default ./config.plist.

What format does vphone-cli use for its configuration files?

vphone-cli uses Apple's standard Property List (plist) format for configuration file storage. The VPhoneVirtualMachineManifest.swift source file handles serialization and deserialization, converting between the XML/binary plist on disk and strongly-typed Swift structures representing the virtual machine hardware specification.

How do I programmatically change settings in a vphone-cli configuration file?

Import the VPhoneCore framework in your Swift project, call VPhoneVirtualMachineManifest.load(from:) with the plist URL, modify the returned structure using methods like updating(memorySize:), and then call write(to:) to persist the changes back to disk. This approach maintains type safety and plist schema integrity.

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