@mcesystems/pmd3-cli

pymobiledevice3 CLI wrapper for Node.js - uses standalone executable

Installation

``bash
npm install @mcesystems/pmd3-cli
`

Usage

`typescript
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'
]);
`

$3

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

`typescript
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.

$3

To rebuild the Python executable:

`bash


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
`

$3

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):
`powershell
python -m pymobiledevice3 remote tunneld
`

macOS:
`bash
sudo python3 -m pymobiledevice3 remote tunneld
`

Then use the CLI with --tunnel parameter:
`typescript
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.