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

### 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

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

### Build from Source

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

### 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):**
```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](../activation-kit/README.md) for full API reference.

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