@mcesystems/pmd3-cli

pymobiledevice3 CLI wrapper for Node.js - uses standalone executable

Installation

npm install @mcesystems/pmd3-cli

Usage

import { runPyMobileDevice, getCliPathInfo } from '@mcesystems/pmd3-cli';

// The package automatically finds the bundled pymobiledevice3 executable
console.log('Using:', getCliPathInfo());

// List connected devices
const result = await runPyMobileDevice(['usbmux', 'list']);
const devices = result.stdout as any[];

// Launch an app
await runPyMobileDevice([
  'developer', 'dvt', 'launch',
  'com.mce.mceFrameworkAgent',
  '--udid', '00008101-000C68290269001E'
]);

CLI Path Resolution

The package automatically resolves the pymobiledevice3 executable path in the following order:

1. PMD_CLI_PATH environment variable - If set, uses this path directly
2. Bundled executable - Automatically finds the executable in dist/bin/pmd3_cli/
3. Python fallback - Falls back to python -m pymobiledevice3 if bundled executable not found

This works seamlessly across:

• Windows: Uses pmd3_cli.exe
• macOS/Linux: Uses pmd3_cli (future support)
• Development: Falls back to Python when running from source
• Production: Uses bundled standalone executable

import { getCliPathInfo, resolveCliPath } from '@mcesystems/pmd3-cli';

// Get human-readable path info
console.log(getCliPathInfo());
// Output: "C:\path\to\dist\bin\pmd3_cli\pmd3_cli.exe (bundled)"

// Get programmatic resolution
const { command, args } = resolveCliPath();
// command: "C:\path\to\dist\bin\pmd3_cli\pmd3_cli.exe"
// args: []

Building

The package includes a pre-built pymobiledevice3 executable (v7.0.7) bundled as a tarball.

Build from Source

To rebuild the Python executable:

# Full Python build with PyInstaller and create prebuild archive
npm run build:python

# Or just rebuild PyInstaller executable
npm run build:python:pyinstaller

# Extract prebuild to dist/bin (done automatically during npm run build)
npm run build:extract-prebuild

Build Requirements

For building Python executable:

• Python 3.10+
• PyInstaller 6.0+
• pymobiledevice3 7.0.7 (installed as regular package, not editable)
• All dependencies from python/requirements.txt

For npm build:

• Node.js 20+
• tar command (available on Windows 10+ and macOS/Linux)

Requirements

• Windows: Requires administrator privileges for tunnel daemon
• macOS: May require sudo for some operations
• iOS Device: Developer Mode must be enabled (iOS 15+)
• Tunnel: For iOS 17+, tunnel daemon must be running manually

Tunnel Daemon

For iOS 17+ devices, you need to run the tunnel daemon manually:

Windows (as Administrator):

python -m pymobiledevice3 remote tunneld

macOS:

sudo python3 -m pymobiledevice3 remote tunneld

Then use the CLI with --tunnel parameter:

import { runPyMobileDevice } from '@mcesystems/pmd3-cli';

await runPyMobileDevice([
  'developer', 'dvt', 'launch',
  'com.mce.mceFrameworkAgent',
  '--udid', '00008101-000C68290269001E',
  '--tunnel', '00008101-000C68290269001E'
]);

API

See activation-kit documentation for full API reference.

The API matches the HTTP service API but uses the CLI executable directly.