https://github.com/appium/node-devicectl
Node.js wrapper around Xcode's devicectl tool
https://github.com/appium/node-devicectl
appium automation devicectl ios
Last synced: 3 months ago
JSON representation
Node.js wrapper around Xcode's devicectl tool
- Host: GitHub
- URL: https://github.com/appium/node-devicectl
- Owner: appium
- License: apache-2.0
- Created: 2025-10-22T12:52:03.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T20:24:13.000Z (4 months ago)
- Last Synced: 2026-03-21T01:14:13.567Z (4 months ago)
- Topics: appium, automation, devicectl, ios
- Language: TypeScript
- Homepage:
- Size: 46.9 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# node-devicectl
Node.js wrapper around Apple's `devicectl` tool, the command-line utility to control iOS devices. `devicectl` is run as a sub-command of xcrun and requires Xcode 15+ and iOS 17+.
## Installation
Install through npm.
```bash
npm install node-devicectl
```
## API
The module exports a single class `Devicectl`. This class contains methods which wrap various devicectl subcommands.
### Advanced Usage
Any devicectl subcommand could be called via `execute` method,
which accepts the subcommand itself as the first argument and the set of options. For example:
```typescript
import { Devicectl } from 'node-devicectl';
const devicectl = new Devicectl('device-udid');
const processes = await devicectl.listProcesses();
await devicectl.launchApp('com.example.app', {
env: { DEBUG: '1' },
terminateExisting: true
});
```
When Node is running under `sudo`, `node-devicectl` runs `xcrun devicectl` as the original
non-root user by default (`SUDO_UID`/`SUDO_GID`) to avoid CoreDevice provider lookup errors.
You can disable this globally via constructor options:
```typescript
const devicectl = new Devicectl('device-udid', {
preferNonRootWhenSudo: false,
});
```
Or override for a single command:
```typescript
await devicectl.execute(['device', 'info'], {
runAsNonRootWhenSudo: false,
});
```
## Requirements
- Xcode 15+
- iOS 17+
- Node.js 20.19.0+ || 22.12.0+ || 24.0.0+
## License
Apache-2.0