feat: add public --launch-args CLI flag for iOS open

main already has internal launchArgs support for iOS simulators (from
the Maestro work). This change makes it a first-class CLI flag and
fills in the gaps:

- Add `--launch-args <arg>` to the schema, allowed flags on `open`,
  and the CLI handler. Mirrors `--header`'s shape (repeatable string
  flag, parsed to `string[]`).
- Plumb `launchArgs` through `AppOpenOptions`, the client
  normalizer, and the standalone `daemon-client.openApp` request
  builder so programmatic callers see the same surface.
- Forward `launchArgs` to iOS device launches via
  `launchIosDeviceProcess`, inserting an explicit `--` end-of-options
  marker before the user's args so devicectl (Swift ArgumentParser)
  can't reparse leading-dash launch args as its own options.
- Reject `launchArgs` explicitly on macOS rather than silently
  dropping them through the existing macOS launch path.
- Reject `launchArgs` combined with an iOS simulator URL open (which
  goes through `simctl openurl`, ignoring launch arguments) with an
  INVALID_ARGS pointing the caller at the two-step flow.

Android remains explicitly rejected in dispatch.ts as already on main;
adding Android support is a separate decision and out of scope here.

Tests:

- `src/utils/__tests__/args.test.ts`: parser/help coverage for
  `--launch-args` including `-FeatureFlag`-style values and
  `--es KEY VALUE`-style values, plus the rejection on unrelated
  commands.
- `src/platforms/ios/__tests__/index.test.ts`: device launch with
  args, device deep-link launch with args (`--` separator after
  `--payload-url`), simulator URL reject, macOS reject.

Author: mikegarfinkle

src/cli/commands/open.ts

@@ -9,6 +9,7 @@ export const openCommand: ClientCommandHandler = async ({ positionals, flags, cl
     surface: flags.surface,
     activity: flags.activity,
     launchConsole: flags.launchConsole,
+    launchArgs: flags.launchArgs,
     relaunch: flags.relaunch,
     saveScript: flags.saveScript,
     noRecord: flags.noRecord,

src/client-normalizers.ts

@@ -276,6 +276,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     surface: options.surface,
     activity: options.activity,
     launchConsole: options.launchConsole,
+    launchArgs: options.launchArgs,
     relaunch: options.relaunch,
     shutdown: options.shutdown,
     saveScript: options.saveScript,

src/client-types.ts

@@ -174,6 +174,7 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     saveScript?: boolean | string;
     noRecord?: boolean;
@@ -847,6 +848,7 @@ export type InternalRequestOptions = AgentDeviceClientConfig &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     shutdown?: boolean;
     saveScript?: boolean | string;

src/commands/session-lifecycle/definition.ts

@@ -29,7 +29,7 @@ const openCommandDefinition = defineCommand({
       'Boot device/simulator; optionally launch app or deep link URL (macOS also supports --surface app|frontmost-app|desktop|menubar)',
     summary: 'Open an app, deep link or URL, save replays',
     positionalArgs: ['appOrUrl?', 'url?'],
-    allowedFlags: ['activity', 'launchConsole', 'saveScript', 'relaunch', 'surface'],
+    allowedFlags: ['activity', 'launchConsole', 'launchArgs', 'saveScript', 'relaunch', 'surface'],
   },
   capability: APP_RUNTIME_CAPABILITY,
 });

src/core/launch-console.ts

@@ -3,3 +3,6 @@ export const LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE =
 
 export const LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE =
   '--launch-console requires a direct app launch and cannot be used with URL opens';
+
+export const IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE =
+  '--launch-args is not supported with iOS simulator URL opens (simctl openurl ignores launch args). Launch the app first with --launch-args, then issue the URL open in a separate call.';

src/daemon-client.ts

@@ -45,6 +45,7 @@ export type OpenAppOptions = {
   serial?: NonNullable<DaemonRequest['flags']>['serial'];
   activity?: NonNullable<DaemonRequest['flags']>['activity'];
   launchConsole?: NonNullable<DaemonRequest['flags']>['launchConsole'];
+  launchArgs?: NonNullable<DaemonRequest['flags']>['launchArgs'];
   out?: NonNullable<DaemonRequest['flags']>['out'];
   saveScript?: NonNullable<DaemonRequest['flags']>['saveScript'];
   relaunch?: boolean;
@@ -203,6 +204,7 @@ export async function openApp(options: OpenAppOptions = {}): Promise<DaemonRespo
     serial,
     activity,
     launchConsole,
+    launchArgs,
     out,
     saveScript,
     relaunch,
@@ -224,6 +226,7 @@ export async function openApp(options: OpenAppOptions = {}): Promise<DaemonRespo
       ...(serial !== undefined ? { serial } : {}),
       ...(activity !== undefined ? { activity } : {}),
       ...(launchConsole !== undefined ? { launchConsole } : {}),
+      ...(launchArgs !== undefined ? { launchArgs } : {}),
       ...(out !== undefined ? { out } : {}),
       ...(saveScript !== undefined ? { saveScript } : {}),
       ...(relaunch ? { relaunch: true } : {}),

src/platforms/ios/__tests__/index.test.ts

@@ -925,6 +925,158 @@ test('openIosApp captures iOS simulator launch console output when requested', a
   }
 });
 
+test('openIosApp appends launchArgs after the bundle id on iOS device', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-launch-args-dev-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    xcrunPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await openIosApp(device, 'MyApp', {
+      appBundleId: 'com.example.app',
+      launchArgs: ['-FeatureFlag', 'YES'],
+    });
+    const args = (await fs.readFile(argsLogPath, 'utf8')).trim().split('\n').filter(Boolean);
+    assert.deepEqual(args, [
+      'devicectl',
+      'device',
+      'process',
+      'launch',
+      '--device',
+      'ios-device-1',
+      'com.example.app',
+      '--',
+      '-FeatureFlag',
+      'YES',
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('openIosApp appends launchArgs alongside --payload-url for iOS device deep links', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-launch-args-deep-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    xcrunPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await openIosApp(device, 'myapp://item/42', {
+      appBundleId: 'com.example.app',
+      launchArgs: ['-Tracking', 'NO'],
+    });
+    const args = (await fs.readFile(argsLogPath, 'utf8')).trim().split('\n').filter(Boolean);
+    assert.deepEqual(args, [
+      'devicectl',
+      'device',
+      'process',
+      'launch',
+      '--device',
+      'ios-device-1',
+      'com.example.app',
+      '--payload-url',
+      'myapp://item/42',
+      '--',
+      '-Tracking',
+      'NO',
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('openIosApp rejects launchArgs combined with URL deep link on iOS simulator', async () => {
+  mockEnsureBootedSimulator.mockResolvedValue();
+  await assert.rejects(
+    () =>
+      openIosApp(IOS_TEST_SIMULATOR, 'myapp://item/42', {
+        launchArgs: ['-FeatureFlag', 'YES'],
+      }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_ARGS');
+      assert.match(String(error.message), /simctl openurl/);
+      return true;
+    },
+  );
+  await assert.rejects(
+    () =>
+      openIosApp(IOS_TEST_SIMULATOR, 'MyApp', {
+        appBundleId: 'com.example.app',
+        url: 'https://example.com/path',
+        launchArgs: ['-FeatureFlag', 'YES'],
+      }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_ARGS');
+      return true;
+    },
+  );
+});
+
+test('openIosApp rejects launchArgs on macOS', async () => {
+  await assert.rejects(
+    () =>
+      openIosApp(MACOS_TEST_DEVICE, 'TextEdit', {
+        launchArgs: ['-FeatureFlag', 'YES'],
+      }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'UNSUPPORTED_OPERATION');
+      assert.match(String(error.message), /macOS/);
+      return true;
+    },
+  );
+});
+
 test('readIosClipboardText rejects physical devices', async () => {
   await assert.rejects(
     () => readIosClipboardText(IOS_TEST_DEVICE),

src/platforms/ios/apps.ts

@@ -6,6 +6,7 @@ import { AppError } from '../../utils/errors.ts';
 import { emitDiagnostic } from '../../utils/diagnostics.ts';
 import type { AppsFilter } from '../../commands/app-inventory-contract.ts';
 import {
+  IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE,
   LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE,
   LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE,
 } from '../../core/launch-console.ts';
@@ -130,10 +131,17 @@ export async function openIosApp(
   options?: { appBundleId?: string; launchConsole?: string; launchArgs?: string[]; url?: string },
 ): Promise<void> {
   const launchConsole = options?.launchConsole?.trim();
+  const launchArgs = options?.launchArgs;
   if (launchConsole && (device.platform !== 'ios' || device.kind !== 'simulator')) {
     throw new AppError('UNSUPPORTED_OPERATION', LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE);
   }
   if (device.platform === 'macos') {
+    if (launchArgs && launchArgs.length > 0) {
+      throw new AppError(
+        'UNSUPPORTED_OPERATION',
+        '--launch-args is not supported on macOS; launch arguments are currently iOS-only.',
+      );
+    }
     await openMacOsApp(device, app, options);
     return;
   }
@@ -146,6 +154,9 @@ export async function openIosApp(
       throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
     }
     if (device.kind === 'simulator') {
+      if (launchArgs && launchArgs.length > 0) {
+        throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
+      }
       await ensureBootedSimulator(device);
       await runSimctl(device, ['openurl', device.id, explicitUrl]);
       return;
@@ -158,7 +169,7 @@ export async function openIosApp(
         'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
       );
     }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: explicitUrl });
+    await launchIosDeviceProcess(device, bundleId, { payloadUrl: explicitUrl, launchArgs });
     return;
   }
 
@@ -168,6 +179,9 @@ export async function openIosApp(
       throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
     }
     if (device.kind === 'simulator') {
+      if (launchArgs && launchArgs.length > 0) {
+        throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
+      }
       await ensureBootedSimulator(device);
       await runSimctl(device, ['openurl', device.id, deepLinkTarget]);
       return;
@@ -179,20 +193,20 @@ export async function openIosApp(
         'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
       );
     }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: deepLinkTarget });
+    await launchIosDeviceProcess(device, bundleId, { payloadUrl: deepLinkTarget, launchArgs });
     return;
   }
 
   const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
   if (device.kind === 'simulator') {
     await launchIosSimulatorApp(device, bundleId, {
       ...(launchConsole ? { launchConsole } : {}),
-      ...(options?.launchArgs ? { launchArgs: options.launchArgs } : {}),
+      ...(launchArgs ? { launchArgs } : {}),
     });
     return;
   }
 
-  await launchIosDeviceProcess(device, bundleId);
+  await launchIosDeviceProcess(device, bundleId, { launchArgs });
 }
 
 export async function openIosDevice(device: DeviceInfo): Promise<void> {
@@ -1059,11 +1073,18 @@ function joinProcessOutput(stdout: string, stderr: string): string {
 async function launchIosDeviceProcess(
   device: DeviceInfo,
   bundleId: string,
-  options?: { payloadUrl?: string },
+  options?: { payloadUrl?: string; launchArgs?: string[] },
 ): Promise<void> {
   const args = ['device', 'process', 'launch', '--device', device.id, bundleId];
   if (options?.payloadUrl) {
     args.push('--payload-url', options.payloadUrl);
   }
+  if (options?.launchArgs && options.launchArgs.length > 0) {
+    // `devicectl` uses Swift ArgumentParser; without `--` an arg starting with
+    // `-` / `--` could be re-interpreted as one of devicectl's own options.
+    // The marker makes the boundary unambiguous so launch args reach the app
+    // verbatim.
+    args.push('--', ...options.launchArgs);
+  }
   await runIosDevicectl(args, { action: 'launch iOS app', deviceId: device.id });
 }

src/utils/__tests__/args.test.ts

@@ -272,6 +272,66 @@ test('parseArgs accepts install-from-source url and repeated headers', () => {
   assert.equal(parsed.flags.retentionMs, 60000);
 });
 
+test('parseArgs accepts open --launch-args with plain values', () => {
+  const parsed = parseArgs(
+    ['open', 'com.example.app', '--launch-args', 'fixtureMode', '--launch-args', 'verbose'],
+    { strictFlags: true },
+  );
+  assert.equal(parsed.command, 'open');
+  assert.deepEqual(parsed.positionals, ['com.example.app']);
+  assert.deepEqual(parsed.flags.launchArgs, ['fixtureMode', 'verbose']);
+});
+
+test('parseArgs accepts open --launch-args with dash-prefixed values', () => {
+  const parsed = parseArgs(
+    [
+      'open',
+      'com.example.app',
+      '--platform',
+      'ios',
+      '--launch-args',
+      '-FeatureFlag',
+      '--launch-args',
+      'YES',
+    ],
+    { strictFlags: true },
+  );
+  assert.equal(parsed.command, 'open');
+  assert.deepEqual(parsed.flags.launchArgs, ['-FeatureFlag', 'YES']);
+});
+
+test('parseArgs accepts open --launch-args with double-dash-prefixed values (am extras style)', () => {
+  const parsed = parseArgs(
+    [
+      'open',
+      'com.example.app',
+      '--launch-args',
+      '--es',
+      '--launch-args',
+      'EXTRA_CONFIG',
+      '--launch-args',
+      '{"mode":"debug"}',
+    ],
+    { strictFlags: true },
+  );
+  assert.equal(parsed.command, 'open');
+  assert.deepEqual(parsed.flags.launchArgs, ['--es', 'EXTRA_CONFIG', '{"mode":"debug"}']);
+});
+
+test('parseArgs rejects --launch-args on commands that do not allow it', () => {
+  assert.throws(
+    () => parseArgs(['tap', '100', '200', '--launch-args', 'foo'], { strictFlags: true }),
+    (error) => error instanceof AppError && error.code === 'INVALID_ARGS',
+  );
+});
+
+test('usageForCommand documents open --launch-args', () => {
+  const help = usageForCommand('open');
+  if (help === null) throw new Error('Expected open help text');
+  assert.match(help, /--launch-args <arg>/);
+  assert.match(help, /forwarded verbatim/);
+});
+
 test('parseArgs accepts install-from-source GitHub Actions artifact flag', () => {
   const parsed = parseArgs(
     [