@houwert/conductor 0.2.0 → 0.3.0

package/dist/index.js

@@ -17,6 +17,7 @@ const swipe_js_1 = require("./commands/swipe.js");
 const assert_visible_js_1 = require("./commands/assert-visible.js");
 const screenshot_js_1 = require("./commands/screenshot.js");
 const inspect_js_1 = require("./commands/inspect.js");
+const focused_js_1 = require("./commands/focused.js");
 const run_flow_js_1 = require("./commands/run-flow.js");
 const run_flow_inline_js_1 = require("./commands/run-flow-inline.js");
 const press_key_js_1 = require("./commands/press-key.js");
@@ -28,6 +29,7 @@ const device_pool_js_1 = require("./commands/device-pool.js");
 const run_parallel_js_1 = require("./commands/run-parallel.js");
 const foreground_app_js_1 = require("./commands/foreground-app.js");
 const list_apps_js_1 = require("./commands/list-apps.js");
+const copy_app_js_1 = require("./commands/copy-app.js");
 const erase_text_js_1 = require("./commands/erase-text.js");
 const assert_not_visible_js_1 = require("./commands/assert-not-visible.js");
 const open_link_js_1 = require("./commands/open-link.js");
@@ -36,100 +38,56 @@ const scroll_until_visible_js_1 = require("./commands/scroll-until-visible.js");
 const set_location_js_1 = require("./commands/set-location.js");
 const set_orientation_js_1 = require("./commands/set-orientation.js");
 const start_device_js_1 = require("./commands/start-device.js");
-const runner_js_1 = require("./runner.js");
+const device_picker_js_1 = require("./device-picker.js");
 const update_check_js_1 = require("./update-check.js");
-const HELP = `
-Usage: conductor <command> [args] [options]
-
-Commands:
-  start-device --platform <ios|android>  Boot a simulator or emulator
-    --os-version <n>                  iOS version (e.g. 18) or Android API level (e.g. 33)
-    --avd <name>                      Android AVD name (default: first available)
-  list-devices                        List connected devices/simulators
-  foreground-app                      Print bundle ID / package of the foreground app
-  list-apps                           List installed app IDs / package names
-  launch-app <appId>                  Launch app (saves to session)
-    --clear-state                     Clear app data/state before launching
-    --clear-keychain                  Clear keychain before launching
-    --no-stop-app                     Do not stop the app before launching (resume instead of restart)
-    --argument key=value              Set launch argument (repeatable)
-  stop-app [<appId>]                  Stop app
-  tap <element>                       Tap element by text or id
-    --id <id>                         Match by accessibility id instead of text
-    --text <text>                     Match by text only (not id)
-    --index <n>                       Pick the nth match (0-based)
-    --long-press                      Hold instead of tap
-    --double-tap                      Double-tap the element
-    --optional                        Do not fail if element is not found
-    --focused                         Match only focused elements
-    --enabled / --no-enabled          Match by enabled state
-    --checked / --no-checked          Match by checked state
-    --selected / --no-selected        Match by selected state
-    --below <text>                    Match element below the given reference
-    --above <text>                    Match element above the given reference
-    --left-of <text>                  Match element left of the given reference
-    --right-of <text>                 Match element right of the given reference
-    --verbose                         Log all candidates and chosen element
-  type <text>                         Type text into focused field
-  erase-text [n]                      Erase n characters (default: 50)
-  back                                Press back button
-  press-key <key>                     Press a key (Enter, Backspace, Home, ...)
-  hide-keyboard                       Dismiss the on-screen keyboard
-  scroll [--direction down|up|left|right]
-  swipe --direction <UP|DOWN|LEFT|RIGHT>
-    --start <x,y>                     Start coordinate (0–1 normalised or absolute px)
-    --end <x,y>                       End coordinate (0–1 normalised or absolute px)
-    --duration <ms>                   Swipe duration in milliseconds (default: 500)
-  scroll-until-visible <element>      Scroll until element is visible
-    --id <id>                         Match by accessibility id instead of text
-    --text <text>                     Match by text only (not id)
-    --direction <down|up|left|right>  Scroll direction (default: down)
-    --timeout <ms>                    Max time in milliseconds (default: 30000)
-  assert-visible <element>            Assert element is visible
-    --id <id>                         Match by accessibility id instead of text
-    --text <text>                     Match by text only (not id)
-    --index <n>                       Pick the nth match (0-based)
-    --timeout <ms>                    Max wait time in milliseconds
-    --optional                        Do not fail if element is not found
-    --focused                         Match only focused elements
-    --enabled / --no-enabled          Match by enabled state
-    --checked / --no-checked          Match by checked state
-    --selected / --no-selected        Match by selected state
-    --below <text>                    Match element below the given reference
-    --above <text>                    Match element above the given reference
-    --left-of <text>                  Match element left of the given reference
-    --right-of <text>                 Match element right of the given reference
-  assert-not-visible <element>        Assert element is absent from screen
-    --id <id>                         Match by accessibility id instead of text
-    --text <text>                     Match by text only (not id)
-    --timeout <ms>                    Max check time in milliseconds (default: 1000)
-  open-link <url>                     Open a URL / deep link
-  set-location --lat <n> --lng <n>    Set GPS coordinates
-  set-orientation <portrait|landscape> Set device orientation
-  screenshot [--output <path>]        Take screenshot
-  inspect                             Print UI hierarchy
-  run-flow <file> [--device <id>]     Run a Maestro YAML flow file
-    --env KEY=VALUE                   Inject env var (repeatable; overrides flow env block)
-    --benchmark                       Print elapsed time for each command and total flow time
-  run-flow-inline <yaml>              Run inline YAML commands
-    --benchmark                       Print elapsed time for each command and total flow time
-  session [--clear] [--list]          Show, clear, or list device sessions
-  cheat-sheet                         Print command reference
-  install                             Install/reinstall Claude Code plugin
-  daemon-start                        Start background daemon (manages driver process)
-  daemon-stop [--all]                 Stop background daemon (--all stops every session's daemon)
-  daemon-status                       Show daemon status
-  device-pool --list                  List all devices and pool status
-  device-pool --acquire               Claim a free device (prints device ID)
-  device-pool --release <id>          Release a device back to the pool
-  run-parallel --flows-dir <path>     Run flows in parallel across all devices
-
-Options:
+const COMMAND_HELP = {
+    'start-device': start_device_js_1.HELP,
+    'list-devices': list_devices_js_1.HELP,
+    'foreground-app': foreground_app_js_1.HELP,
+    'list-apps': list_apps_js_1.HELP,
+    'copy-app': copy_app_js_1.HELP,
+    'launch-app': launch_app_js_1.HELP,
+    'stop-app': stop_app_js_1.HELP,
+    tap: tap_js_1.HELP,
+    type: type_js_1.HELP,
+    'erase-text': erase_text_js_1.HELP,
+    back: back_js_1.HELP,
+    'press-key': press_key_js_1.HELP,
+    'hide-keyboard': hide_keyboard_js_1.HELP,
+    scroll: scroll_js_1.HELP,
+    swipe: swipe_js_1.HELP,
+    'scroll-until-visible': scroll_until_visible_js_1.HELP,
+    'assert-visible': assert_visible_js_1.HELP,
+    'assert-not-visible': assert_not_visible_js_1.HELP,
+    'open-link': open_link_js_1.HELP,
+    'set-location': set_location_js_1.HELP,
+    'set-orientation': set_orientation_js_1.HELP,
+    screenshot: screenshot_js_1.HELP,
+    inspect: inspect_js_1.HELP,
+    focused: focused_js_1.HELP,
+    'run-flow': run_flow_js_1.HELP,
+    'run-flow-inline': run_flow_inline_js_1.HELP,
+    session: session_js_1.HELP,
+    'cheat-sheet': cheat_sheet_js_1.HELP,
+    install: install_js_1.HELP,
+    'daemon-start': daemon_js_1.HELP_DAEMON_START,
+    'daemon-stop': daemon_js_1.HELP_DAEMON_STOP,
+    'daemon-status': daemon_js_1.HELP_DAEMON_STATUS,
+    'device-pool': device_pool_js_1.HELP,
+    'run-parallel': run_parallel_js_1.HELP,
+};
+const OPTIONS_HELP = `Options:
   --device <id>     Target device ID (also keys the session and daemon)
+  --device-name <n> Target a booted device by name (resolved to ID from booted devices)
   --json            Output as machine-readable JSON
   --verbose, -v     Log daemon calls, fallbacks, and raw output
-  --help, -h        Show this help
-`.trim();
+  --help, -h        Show this help`;
+const HELP = `Usage: conductor <command> [args] [options]
+
+Commands:
+${Object.values(COMMAND_HELP).join('\n')}
+
+${OPTIONS_HELP}`;
 async function main() {
     (0, update_check_js_1.checkForUpdates)();
     const argv = (0, minimist_1.default)(process.argv.slice(2), {
@@ -140,6 +98,7 @@ async function main() {
             'list',
             'verbose',
             'skills',
+            'check',
             'all',
             'acquire',
             'release',
@@ -150,6 +109,7 @@ async function main() {
             'double-tap',
             'optional',
             'benchmark',
+            'dump',
         ],
         string: [
             'device',
@@ -171,6 +131,11 @@ async function main() {
             'platform',
             'os-version',
             'avd',
+            'name',
+            'device-name',
+            'device-type',
+            'from',
+            'to',
         ],
         alias: { h: 'help', v: 'verbose' },
     });
@@ -178,20 +143,64 @@ async function main() {
         (0, verbose_js_1.setVerbose)(true);
     const [command, ...rest] = argv._;
     const opts = { json: argv['json'] };
-    // The device ID is the natural key for both the session file and the daemon.
-    // Use --device if given, otherwise detect the first booted device, otherwise 'default'.
-    const explicitDevice = argv['device'];
-    const sessionName = explicitDevice ?? (await (0, runner_js_1.detectFirstDevice)()) ?? 'default';
+    // Handle help and unknown commands before device resolution —
+    // no point prompting for a device if we're just printing help or erroring out.
     if (!command || argv['help']) {
-        console.log(HELP);
+        if (command && argv['help'] && COMMAND_HELP[command]) {
+            console.log(`Usage: conductor ${command} [options]\n\n${COMMAND_HELP[command]}\n\n${OPTIONS_HELP}`);
+        }
+        else {
+            console.log(HELP);
+        }
         process.exit(0);
     }
+    // Commands that don't need a device session
+    const NO_DEVICE_COMMANDS = new Set([
+        'list-devices',
+        'start-device',
+        'cheat-sheet',
+        'install',
+        'copy-app',
+        'device-pool',
+        'run-parallel',
+    ]);
+    if (!NO_DEVICE_COMMANDS.has(command) && !COMMAND_HELP[command]) {
+        console.error(`Unknown command: ${command}`);
+        console.error('Run `conductor --help` for usage.');
+        process.exit(1);
+    }
+    // The device ID is the natural key for both the session file and the daemon.
+    // Use --device if given, otherwise detect the first booted device, otherwise 'default'.
+    // Only resolve for commands that actually need a device.
+    let sessionName = 'default';
+    if (!NO_DEVICE_COMMANDS.has(command)) {
+        const explicitDevice = argv['device'];
+        const deviceName = argv['device-name'];
+        if (explicitDevice && deviceName) {
+            console.error('Error: --device and --device-name are mutually exclusive.');
+            process.exit(1);
+        }
+        if (deviceName) {
+            const devices = await (0, list_devices_js_1.discoverBootedDevices)();
+            const match = devices.find((d) => d.name === deviceName);
+            if (!match) {
+                console.error(`Error: No booted device found with name "${deviceName}". Run \`conductor list-devices\` to see booted devices.`);
+                process.exit(1);
+            }
+            sessionName = match.id;
+        }
+        else {
+            sessionName = explicitDevice ?? (await (0, device_picker_js_1.pickDevice)()) ?? 'default';
+        }
+    }
     let exitCode = 0;
     switch (command) {
         case 'start-device':
             exitCode = await (0, start_device_js_1.startDevice)(argv['platform'], opts, {
                 osVersion: argv['os-version'],
                 avd: argv['avd'],
+                name: argv['name'],
+                deviceType: argv['device-type'],
             });
             break;
         case 'list-devices':
@@ -203,6 +212,13 @@ async function main() {
         case 'list-apps':
             exitCode = await (0, list_apps_js_1.listApps)(opts, sessionName);
             break;
+        case 'copy-app': {
+            const bundleId = rest[0] ?? '';
+            const from = argv['from'];
+            const to = argv['to'];
+            exitCode = await (0, copy_app_js_1.copyApp)(bundleId, from ?? '', to ?? '', opts);
+            break;
+        }
         case 'launch-app': {
             const appId = rest[0] ?? '';
             // --argument key=value (repeatable) → Record<string, string>
@@ -366,7 +382,13 @@ async function main() {
             break;
         }
         case 'inspect':
-            exitCode = await (0, inspect_js_1.inspect)(opts, sessionName);
+            exitCode = await (0, inspect_js_1.inspect)(opts, sessionName, { dump: argv['dump'] });
+            break;
+        case 'focused':
+            exitCode = await (0, focused_js_1.focused)(opts, sessionName, {
+                poll: argv['poll'],
+                interval: argv['interval'] !== undefined ? Number(argv['interval']) : undefined,
+            });
             break;
         case 'run-flow': {
             const file = rest[0] ?? '';
@@ -388,7 +410,7 @@ async function main() {
             exitCode = await (0, cheat_sheet_js_1.cheatSheet)();
             break;
         case 'install':
-            exitCode = await (0, install_js_1.installSkills)(opts);
+            exitCode = await (0, install_js_1.installSkills)(opts, argv['skills'], argv['check']);
             break;
         case 'daemon-start':
             exitCode = await (0, daemon_js_1.daemonStart)(opts, sessionName);
@@ -413,6 +435,7 @@ async function main() {
             break;
         }
         default:
+            // Should be unreachable — unknown commands are caught before device resolution.
             console.error(`Unknown command: ${command}`);
             console.error('Run `conductor --help` for usage.');
             exitCode = 1;

package/dist/postinstall.js

@@ -4,8 +4,8 @@ const install_js_1 = require("./commands/install.js");
 // Runs as `postinstall` after `npm install -g @houwert/conductor`.
 // Silent on failure so it never breaks the npm install.
 try {
-    (0, install_js_1.installPlugin)();
-    process.stdout.write('✓ Conductor Claude Code plugin installed\n');
+    const version = (0, install_js_1.installPlugin)();
+    process.stdout.write(`✓ Conductor Claude Code plugin installed (v${version})\n`);
 }
 catch {
     // Silent on failure — never break npm install

package/dist/runner.js

@@ -95,20 +95,54 @@ async function getDriver(sessionName = 'default') {
     const port = await (0, bootstrap_js_1.getDriverPort)(platform, deviceId);
     (0, verbose_js_1.log)(`getDriver: platform=${platform} deviceId=${deviceId} port=${port}`);
     let driver;
-    if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
-        (0, verbose_js_1.log)(`Driver not running — starting daemon for ${deviceId}...`);
-        await (0, client_js_1.startDaemon)(deviceId);
-        await waitForPort(port);
-    }
     if (platform === 'ios') {
-        const iosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId);
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+            (0, verbose_js_1.log)(`Driver not running — starting daemon for ${deviceId}...`);
+            await (0, client_js_1.startDaemon)(deviceId);
+            await waitForPort(port);
+        }
+        const iosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'ios');
         if (!(await iosDriver.isAlive())) {
             throw new Error(`iOS XCTest driver on port ${port} is not responding.\n` +
                 `Run: conductor daemon-start --device ${deviceId}`);
         }
         driver = iosDriver;
     }
+    else if (platform === 'tvos') {
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+            (0, verbose_js_1.log)(`tvOS driver not running — starting daemon for ${deviceId}...`);
+            await (0, client_js_1.startDaemon)(deviceId);
+            await waitForPort(port);
+        }
+        const tvosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'tvos');
+        if (!(await tvosDriver.isAlive())) {
+            throw new Error(`tvOS XCTest driver on port ${port} is not responding.\n` +
+                `Run: conductor daemon-start --device ${deviceId}`);
+        }
+        driver = tvosDriver;
+    }
     else {
+        // Ensure the daemon is running — it handles APK install and driver startup.
+        await (0, client_js_1.startDaemon)(deviceId);
+        // Poll isAlive() directly instead of isPortOpen(): with ADB port forwarding the
+        // local port appears open as soon as `adb forward` runs, before the gRPC server
+        // on the device is ready, making isPortOpen() unreliable as a readiness signal.
+        const ANDROID_READY_TIMEOUT_MS = 180000;
+        const deadline = Date.now() + ANDROID_READY_TIMEOUT_MS;
+        let alive = false;
+        while (Date.now() < deadline) {
+            const probe = new android_js_1.AndroidDriver(deviceId, port);
+            await probe.connect();
+            alive = await probe.isAlive().catch(() => false);
+            probe.close();
+            if (alive)
+                break;
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+        if (!alive) {
+            throw new Error(`Android gRPC driver on port ${port} is not responding.\n` +
+                `Make sure the Conductor driver APK is installed: conductor install --device ${deviceId}`);
+        }
         const androidDriver = new android_js_1.AndroidDriver(deviceId, port);
         await androidDriver.connect();
         driver = androidDriver;

package/drivers/tvos/conductor-driver-tvos-config.xctestrun

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>__xctestrun_metadata__</key>
+	<dict>
+		<key>ContainerInfo</key>
+		<dict>
+			<key>ContainerName</key>
+			<string>conductor-driver-ios</string>
+			<key>SchemeName</key>
+			<string>conductor-driver-tvos</string>
+		</dict>
+		<key>FormatVersion</key>
+		<integer>1</integer>
+	</dict>
+	<key>conductor-driver-tvosUITests</key>
+	<dict>
+		<key>BlueprintName</key>
+		<string>conductor-driver-tvosUITests</string>
+		<key>BlueprintProviderName</key>
+		<string>conductor-driver-ios</string>
+		<key>BlueprintProviderRelativePath</key>
+		<string>conductor-driver-ios.xcodeproj</string>
+		<key>BundleIdentifiersForCrashReportEmphasis</key>
+		<array>
+			<string>dev.houwert.ConductorDriverLib</string>
+			<string>dev.houwert.conductor-driver-tvos</string>
+			<string>dev.houwert.conductor-driver-tvosUITests</string>
+		</array>
+		<key>CommandLineArguments</key>
+		<array/>
+		<key>DefaultTestExecutionTimeAllowance</key>
+		<integer>600</integer>
+		<key>DependentProductPaths</key>
+		<array>
+			<string>__TESTROOT__/Debug-appletvsimulator/ConductorDriverLib.framework</string>
+			<string>__TESTROOT__/Debug-appletvsimulator/conductor-driver-tvos.app</string>
+			<string>__TESTROOT__/Debug-appletvsimulator/conductor-driver-tvosUITests-Runner.app</string>
+			<string>__TESTROOT__/Debug-appletvsimulator/conductor-driver-tvosUITests-Runner.app/PlugIns/conductor-driver-tvosUITests.xctest</string>
+		</array>
+		<key>DiagnosticCollectionPolicy</key>
+		<integer>1</integer>
+		<key>EnvironmentVariables</key>
+		<dict>
+			<key>APP_DISTRIBUTOR_ID_OVERRIDE</key>
+			<string>com.apple.AppStore</string>
+			<key>OS_ACTIVITY_DT_MODE</key>
+			<string>YES</string>
+			<key>SQLITE_ENABLE_THREAD_ASSERTIONS</key>
+			<string>1</string>
+			<key>TERM</key>
+			<string>dumb</string>
+		</dict>
+		<key>IsUITestBundle</key>
+		<true/>
+		<key>IsXCTRunnerHostedTestBundle</key>
+		<true/>
+		<key>PreferredScreenCaptureFormat</key>
+		<string>screenRecording</string>
+		<key>ProductModuleName</key>
+		<string>conductor_driver_tvosUITests</string>
+		<key>RunOrder</key>
+		<integer>0</integer>
+		<key>SystemAttachmentLifetime</key>
+		<string>deleteOnSuccess</string>
+		<key>TestBundlePath</key>
+		<string>__TESTHOST__/PlugIns/conductor-driver-tvosUITests.xctest</string>
+		<key>TestHostBundleIdentifier</key>
+		<string>dev.houwert.conductor-driver-tvosUITests.xctrunner</string>
+		<key>TestHostPath</key>
+		<string>__TESTROOT__/Debug-appletvsimulator/conductor-driver-tvosUITests-Runner.app</string>
+		<key>TestLanguage</key>
+		<string></string>
+		<key>TestRegion</key>
+		<string></string>
+		<key>TestTimeoutsEnabled</key>
+		<false/>
+		<key>TestingEnvironmentVariables</key>
+		<dict>
+			<key>DYLD_FRAMEWORK_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator:__TESTROOT__/Debug-appletvsimulator/PackageFrameworks:__PLATFORMS__/AppleTVSimulator.platform/Developer/Library/Frameworks</string>
+			<key>DYLD_LIBRARY_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator:__PLATFORMS__/AppleTVSimulator.platform/Developer/usr/lib</string>
+			<key>XCODE_SCHEME_NAME</key>
+			<string>conductor-driver-tvos</string>
+			<key>__XCODE_BUILT_PRODUCTS_DIR_PATHS</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+			<key>__XPC_DYLD_FRAMEWORK_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+			<key>__XPC_DYLD_LIBRARY_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+		</dict>
+		<key>ToolchainsSettingValue</key>
+		<array/>
+		<key>UITargetAppCommandLineArguments</key>
+		<array/>
+		<key>UITargetAppEnvironmentVariables</key>
+		<dict>
+			<key>APP_DISTRIBUTOR_ID_OVERRIDE</key>
+			<string>com.apple.AppStore</string>
+			<key>DYLD_FRAMEWORK_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator:__TESTROOT__/Debug-appletvsimulator/PackageFrameworks</string>
+			<key>DYLD_LIBRARY_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+			<key>XCODE_SCHEME_NAME</key>
+			<string>conductor-driver-tvos</string>
+			<key>__XCODE_BUILT_PRODUCTS_DIR_PATHS</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+			<key>__XPC_DYLD_FRAMEWORK_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+			<key>__XPC_DYLD_LIBRARY_PATH</key>
+			<string>__TESTROOT__/Debug-appletvsimulator</string>
+		</dict>
+		<key>UITargetAppPath</key>
+		<string>__TESTROOT__/Debug-appletvsimulator/conductor-driver-tvos.app</string>
+		<key>UserAttachmentLifetime</key>
+		<string>deleteOnSuccess</string>
+	</dict>
+</dict>
+</plist>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor/SKILL.md

@@ -1,3 +1,13 @@
+---
+name: conductor
+version: 0.2.0
+description: "Token-efficient CLI for mobile UI testing (iOS simulator + Android emulator), designed for AI agents"
+metadata.openclaw:
+  category: service
+  requires:
+    bins: [conductor]
+---
+
 # conductor
 
 A token-efficient CLI for Conductor mobile UI testing, designed for AI agents.
@@ -10,6 +20,7 @@ conductor <command> [args] [options]
 
 Global options:
 - `--device <id>` — target device ID; also keys the session and daemon (auto-detected if omitted)
+- `--device-name <name>` — target a booted device by its human-readable name (resolved to ID from booted devices); mutually exclusive with `--device`
 - `--help` — show help
 - `--json` — machine-readable JSON output (avoid unless you need structured parsing)
 - `--verbose / -v` — log daemon calls, driver fallbacks, and raw output
@@ -20,7 +31,7 @@ Global options:
 
 ### `list-devices`
 
-List connected Android emulators and iOS simulators.
+List connected Android emulators and iOS simulators. Shows both booted (running) devices and available (shutdown) simulators/emulators that can be started with `start-device`.
 
 ```bash
 conductor list-devices
@@ -28,10 +39,17 @@ conductor list-devices
 
 Output:
 ```
-android    device     emulator-5554  Pixel_6_API_33
-ios        booted     ABC123-DEF456  iPhone 15
+Booted devices:
+  android  device     emulator-5554  Pixel_6_API_33
+  ios      booted     ABC123-DEF456  iPhone 15
+
+Available devices:
+  ios      shutdown   DEF789-ABC012  iPhone 16 Pro
+  android  available  Pixel_7_API_34  Pixel_7_API_34
 ```
 
+Exits with code 0 if any booted or available devices exist, 1 only if both lists are empty.
+
 ---
 
 ### `foreground-app`
@@ -56,6 +74,22 @@ conductor list-apps --device emulator-5554
 
 ---
 
+### `copy-app <bundleId>`
+
+Copy an installed app from one iOS simulator to another. Useful when you have a compiled `.app` bundle on one simulator and want to install it on others without recompiling.
+
+```bash
+conductor copy-app com.example.myapp --from C59D3241-FB6A-4E3B-AE7B-A82D3C933889 --to 86B1BC33-7D83-47FF-AAFE-1BD70FC53038
+```
+
+Flags:
+- `--from <id>` — source device ID (must be an iOS simulator)
+- `--to <id>` — target device ID (must be an iOS simulator)
+
+Both flags are required. The command reads the `.app` bundle path from the source simulator and installs it on the target.
+
+---
+
 ### `launch-app <appId>`
 
 Launch an app by bundle ID and save it to the session.
@@ -159,9 +193,9 @@ conductor back
 
 ### `press-key <key>`
 
-Press a hardware or keyboard key. Valid keys: `Enter`, `Backspace`, `Home`, `End`, `Tab`, `Delete`, `Escape`, `VolumeUp`, `VolumeDown`, `Power`, `Lock`, `Back`, `Camera`, `Search`.
+Press a hardware or keyboard key. Valid keys: `Enter`, `Backspace`, `Home`, `End`, `Tab`, `Delete`, `Escape`, `VolumeUp`, `VolumeDown`, `Power`, `Lock`, `Back`, `Camera`, `Search`, `Remote Dpad Up`, `Remote Dpad Down`, `Remote Dpad Left`, `Remote Dpad Right`, `Remote Dpad Center`.
 
-Not all keys are supported on all platforms — unsupported keys are silently ignored (e.g. `Back` on iOS).
+Not all keys are supported on all platforms — unsupported keys are silently ignored (e.g. `Back` on iOS). The `Remote Dpad *` keys are Android TV only.
 
 ```bash
 conductor press-key Enter
@@ -659,6 +693,8 @@ Boot an iOS simulator or Android emulator. Creates the Simulator window and wait
 conductor start-device --platform ios
 conductor start-device --platform android
 conductor start-device --platform ios --os-version 18
+conductor start-device --platform ios --device-type "iPhone 16 Pro"
+conductor start-device --platform ios --name "Test Device"
 conductor start-device --platform android --avd Pixel_6_API_33
 ```
 
@@ -666,8 +702,10 @@ Flags:
 - `--platform <ios|android>` — required
 - `--os-version <n>` — filter by OS version (iOS: e.g. `18`; Android: API level e.g. `33`)
 - `--avd <name>` — Android AVD name to launch (default: first available AVD)
+- `--name <name>` — set a custom name on the simulator after boot (iOS only)
+- `--device-type <name>` — iOS device type to boot (e.g. `"iPhone 16 Pro"`); if no existing simulator matches, one is created automatically
 
-iOS picks the first available iPhone simulator matching the OS version filter (or any if unfiltered). Android launches the named AVD, or the first AVD found.
+iOS picks the first available iPhone simulator matching the OS version and device type filters (or any if unfiltered). Android launches the named AVD, or the first AVD found.
 
 ---
 

package/skills/conductor/references/flow-syntax.md

@@ -51,6 +51,7 @@ appId: com.example.myapp
 - pressKey: Enter
 - pressKey: Backspace
 - pressKey: Home
+- pressKey: Remote Dpad Down  # Android TV only; also Up, Left, Right, Center, Remote Media Play Pause, Remote Media Stop, Remote Media Next, Remote Media Previous, Remote Media Rewind, Remote Media Fast Forward, Remote System Navigation Up, Remote System Navigation Down, Remote Button A, Remote Button B, Remote Menu, TV Input, TV Input HDMI 1/2/3
 - pasteText: "pasted content" # paste text into focused field
 - copyTextFrom: "Element"     # copy element's text to output.textContent
 ```

package/skills/skills.yaml

@@ -0,0 +1,8 @@
+skills:
+  - name: conductor
+    path: conductor/SKILL.md
+    description: "Token-efficient CLI for mobile UI testing, designed for AI agents"
+    category: service
+    version: 0.2.0
+    requires:
+      bins: [conductor]