# node-devicectl

> Node.js wrapper around Apple's devicectl tool

Latest version **2.2.1** (published 2026-10-08) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install node-devicectl
pnpm add node-devicectl
yarn add node-devicectl
bun add node-devicectl
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.1 |
| Published | 2026-10-08 |
| First published | 2025-10-23 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0 |
| Dependencies | 2 |
| Unpacked size | 82.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Appium Contributors |
| Maintainers | jlipps, nick.mokhnach, kazucocoa |
| Keywords | apple, device, devicectl, ios, xcode |

## Links

- npm: https://www.npmjs.com/package/node-devicectl
- Repository: https://github.com/appium/appium-ios
- Homepage: https://github.com/appium/appium-ios#readme
- Issues: https://github.com/appium/appium-ios/issues
- npm.io page: https://npm.io/package/node-devicectl

## Dependencies (2)

- [teen_process](https://npm.io/package/teen_process.md) ^4.1.0
- [@appium/logger](https://npm.io/package/@appium/logger.md) ^2.0.0-rc.1

## Recent versions

- 2.2.1 (latest) — 2026-10-08
- 2.2.0 — 2026-10-02
- 2.1.1 — 2026-10-02
- 2.1.0 — 2026-07-25
- 2.0.1 — 2026-07-25
- 2.0.0 — 2026-07-24
- 1.4.3 — 2026-07-06
- 1.4.2 — 2026-07-06
- 1.4.1 — 2026-07-02
- 1.4.0 — 2026-05-16
- 1.3.1 — 2026-05-08
- 1.3.0 — 2026-04-25
- 1.2.1 — 2026-04-10
- 1.2.0 — 2026-03-20
- 1.1.5 — 2026-03-20
- … 7 more at https://npm.io/package/node-devicectl/versions

## 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
});
await devicectl.terminateApp('com.example.app');
await devicectl.terminateApp('com.example.app', { force: 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

---
_Source: https://npm.io/package/node-devicectl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._