# Complete Guide to vphone-cli Message Types for Guest Communication

> Explore vphone-cli message types for guest communication. Discover 30+ supported JSON message types for handshake file transfer app management and system control in this comprehensive guide.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: api-reference
- Published: 2026-09-09

---

**vphone-cli communicates with the guest-side daemon over VSock using a length-prefixed JSON protocol supporting 30+ distinct message types for handshake, input injection, file transfer, app management, and system control.**

The open-source tool **vphone-cli** (maintained in `Lakr233/vphone-cli`) implements a host-side Swift client that orchestrates virtualized iOS devices. Every message exchanged with the guest daemon **vphoned** follows a strict JSON envelope containing a protocol version (`"v"`), message type (`"t"`), and an optional request identifier (`"id"`). Understanding these supported message types is essential for extending the tool or debugging guest communication failures.

## Protocol Structure and Conventions

All frames are length-prefixed JSON objects sent over a VSock connection on port 1337. The host (Swift) and guest (Objective-C) share an identical vocabulary. Message types determine the payload schema and expected directionality.

In [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift), the `sendCommand` method serializes requests while the read loop dispatches responses based on the `"t"` field. Timeouts and error handling are managed per-type in this single source file.

## Host-to-Guest Request Types

These message types originate from the host CLI and trigger actions inside the guest operating system.

### System Handshake and Lifecycle

- **hello** – Sent during `performHandshake` (lines 76-84) to announce the host identity and transmit an optional binary hash for version verification.
- **ping** – Liveness check implemented in `sendPing` (lines 36-37) expecting a `pong` response.
- **version** – Retrieves the guest build hash via `sendVersion` (lines 40-42).
- **update** – Pushes a raw binary payload to the guest when `pushUpdate` (lines 50-53) detects a version mismatch.
- **devmode** – Queries developer mode status through `sendDevModeStatus` (lines 30-33).
- **low_power_mode** – Toggles power state via `lowPowerMode` (lines 87-92).

### Input Injection

- **hid** – Transmits keyboard events through `sendHIDPress` and `sendHIDRelease` (lines 86-95) using HID page and usage codes.
- **touch** – Sends digitizer events via `sendTouch` (lines 10-18) with phase values: `0` for down, `1` for move, and `3` for up.

### File System Operations

The protocol supports full remote file management inside the guest sandbox:

- **file_list** – Directory enumeration from `listFiles` (lines 81-84) returning metadata arrays.
- **file_get** – Binary download initiated by `downloadFile` (lines 90-94).
- **file_put** – Upload via `uploadFile` (lines 100-108) streaming raw bytes.
- **file_mkdir** – Directory creation in `createDirectory` (lines 42-44).
- **file_delete** – Removal command from `deleteFile` (lines 46-48).
- **file_rename** – Move or rename operations via `renameFile` (lines 50-52).

### Application Management

- **app_list** – Enumerates installed applications through `appList` (lines 22-27).
- **app_launch** – Starts applications optionally with URL payloads via `appLaunch` (lines 40-45).
- **app_terminate** – Force-quits running apps using `appTerminate` (lines 48-49).
- **app_foreground** – Queries the currently focused application in `appForeground` (lines 52-58).
- **ipa_install** – Installs iOS packages through `installIPA` (lines 64-67).

### Security and Clipboard

- **keychain_list** – Retrieves stored credentials via `listKeychainItems` (lines 16-20).
- **keychain_add** – Inserts new keychain entries using `addKeychainItem` (lines 27-33).
- **clipboard_get** – Reads pasteboard contents (text and image) from `clipboardGet` (lines 52-56).
- **clipboard_set** – Writes text or binary image data via `clipboardSet` (lines 63-71).

### System Settings and URLs

- **settings_get** – Reads user defaults or system preferences in `settingsGet` (lines 74-78).
- **settings_set** – Writes configuration values through `settingsSet` (lines 80-84).
- **open_url** – Requests the guest open a specific URL scheme via `openURL` (lines 62-66).

### Advanced Diagnostics and Location

- **accessibility_tree** – Dumps the UIAccessibility hierarchy via `accessibilityTree` (lines 97-102) for automation debugging.
- **location** – Streams GPS coordinates, speed, and altitude updates from `sendLocation` (lines 112-125).
- **location_stop** – Terminates location updates using `sendLocationStop` (lines 133-138).

## Guest-to-Host Response Types

The guest daemon sends these types back to the host, typically as acknowledgments or data payloads.

- **ok** – Generic success response handled in the read loop default case (lines 44-48), optionally containing a message string.
- **pong** – Explicit response to `ping` requests (lines 49-51).
- **version** – Returns the guest build hash (lines 52-55).
- **err** – Error indication carrying a `"msg"` field, caught as `ControlError.guestError` in the host (lines 56-58).
- **file_data** – Inline binary payload for `file_get` responses (lines 95-110).
- **clipboard_get** – Binary image data when clipboard contains non-text content (lines 15-21).

## Bidirectional Common Types

Certain types appear in both directions with context-specific payloads:

- **hello** (guest side) – Response during handshake (lines 98-104) carrying guest name, capabilities, IP address, iOS version, and update requirements.
- **need_update** – Boolean flag inside the guest `hello` payload (line 104) triggering the host's `update` sequence.

## Implementation in VPhoneControl.swift

The entire protocol implementation resides in [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift). Key architectural details include:

- VSock connection establishment through [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) (port 1337).
- Request/response correlation using the `"id"` field for async/await bridging.
- Timeout handling per message category (file transfers allow longer durations than pings).
- Guest daemon scripts in `scripts/vphoned/*` mirror this type vocabulary in Objective-C.

## Practical Code Examples

Sending a HID keyboard shortcut to hide the current app:

```swift
let control = VPhoneControl(variant: .regular)
control.sendHIDPress(page: 0x07, usage: 0x0b)   // Command + H

```

Requesting the UI accessibility tree for automation:

```swift
let tree = try await control.accessibilityTree(depth: 3)
print(tree)

```

Uploading and retrieving a file from the guest:

```swift
await control.uploadFile(path: "/tmp/example.txt",
                        data: Data("Hello".utf8))
let data = try await control.downloadFile(path: "/tmp/example.txt")
print(String(data: data, encoding: .utf8) ?? "-")

```

Handling guest-side errors explicitly:

```swift
do {
    try await control.sendPing()
} catch VPhoneControl.ControlError.guestError(let msg) {
    print("Guest reported error: \(msg)")
}

```

## Summary

- **vphone-cli** uses a length-prefixed JSON protocol over VSock with mandatory `"v"` (version) and `"t"` (type) fields.
- **Host-initiated types** cover handshake (`hello`), input (`hid`, `touch`), file operations (`file_*`), app lifecycle (`app_*`), and system control (`settings_*`, `location`).
- **Guest response types** include status codes (`ok`, `err`), data payloads (`file_data`, `clipboard_get`), and liveness checks (`pong`).
- All message types are implemented in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) with specific line-numbered handlers for serialization and parsing.
- The protocol supports binary blob transfer for files, images, and clipboard contents alongside structured JSON metadata.

## Frequently Asked Questions

### What transport protocol does vphone-cli use for guest communication?

vphone-cli establishes a VSock (Virtio Socket) connection on port 1337 to the guest-side daemon. Messages are length-prefixed JSON objects, ensuring framing integrity when transmitting binary payloads like file contents or HID reports.

### How does vphone-cli handle asynchronous responses from the guest?

The host correlates requests and responses using an optional `"id"` field in the JSON envelope. The Swift implementation in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) maintains an internal continuation map that resumes async/await calls when matching response types (like `ok`, `file_data`, or `err`) arrive with the corresponding identifier.

### Can vphone-cli transfer binary files between host and guest?

Yes. The `file_put` and `file_get` message types support raw binary transmission. When uploading, the host sends the binary payload immediately after the JSON header. When downloading, the guest responds with a `file_data` frame containing the raw bytes, handled in [`VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneControl.swift) lines 95-110.

### What happens when the guest vphoned daemon needs an update?

During the initial `hello` handshake (lines 76-104), the guest sets a `need_update` boolean flag if its binary hash differs from the host's. The host then sends an `update` message type via `pushUpdate` (lines 50-53) containing the new daemon binary, which the guest replaces atomically before reconnecting.