feat: expose iOS launch args for open (#598)

mikegarfinkle · thymikee · web-flow · commit dc37f86931a3 · 2026-05-30T16:06:32.000+02:00
Co-authored-by: Michał Pierzchała &lt;thymikee@gmail.com&gt;
diff --git a/src/__tests__/cli-client-commands.test.ts b/src/__tests__/cli-client-commands.test.ts
@@ -537,13 +537,15 @@ test('open forwards launch console option to the client apps API', async () => {
       version: false,
       platform: 'ios',
       launchConsole: '/tmp/launch-console.log',
+      launchArgs: ['-FeatureFlag', 'YES'],
     },
     client,
   });
 
   assert.equal(handled, true);
   assert.equal(observed?.platform, 'ios');
   assert.equal(observed?.launchConsole, '/tmp/launch-console.log');
+  assert.deepEqual(observed?.launchArgs, ['-FeatureFlag', 'YES']);
 });
 
 test('apps command defaults to user-installed and prints discovery hint', async () => {
diff --git a/src/__tests__/runtime-apps.test.ts b/src/__tests__/runtime-apps.test.ts
@@ -20,6 +20,7 @@ test('runtime app commands call typed backend lifecycle primitives', async () =>
   const opened = await device.apps.open({
     session: 'default',
     app: ' com.example.app ',
+    launchArgs: ['-FeatureFlag', 'YES'],
     relaunch: true,
   });
   assert.deepEqual(opened, {
@@ -61,7 +62,7 @@ test('runtime app commands call typed backend lifecycle primitives', async () =>
     {
       command: 'openApp',
       target: { app: 'com.example.app' },
-      options: { relaunch: true },
+      options: { launchArgs: ['-FeatureFlag', 'YES'], relaunch: true },
       session: 'default',
     },
     { command: 'closeApp', app: 'com.example.app' },
diff --git a/src/backend.ts b/src/backend.ts
@@ -195,6 +195,7 @@ export type BackendOpenTarget = {
 };
 
 export type BackendOpenOptions = {
+  launchArgs?: string[];
   relaunch?: boolean;
 };
 
diff --git a/src/client-normalizers.ts b/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,
diff --git a/src/client-types.ts b/src/client-types.ts
@@ -175,6 +175,7 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     saveScript?: boolean | string;
     noRecord?: boolean;
@@ -844,6 +845,7 @@ export type InternalRequestOptions = AgentDeviceClientConfig &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     shutdown?: boolean;
     saveScript?: boolean | string;
diff --git a/src/commands/apps.ts b/src/commands/apps.ts
@@ -22,6 +22,7 @@ const MAX_APP_PUSH_PAYLOAD_BYTES = 8 * 1024;
 
 export type OpenAppCommandOptions = CommandContext &
   BackendOpenTarget & {
+    launchArgs?: string[];
     relaunch?: boolean;
   };
 
@@ -109,6 +110,7 @@ export const openAppCommand: RuntimeCommand<OpenAppCommandOptions, OpenAppComman
     toAppBackendContext(runtime, options),
     target,
     {
+      launchArgs: options.launchArgs,
       relaunch: options.relaunch,
     },
   );
diff --git a/src/commands/cli-grammar/apps.ts b/src/commands/cli-grammar/apps.ts
@@ -36,6 +36,7 @@ export const appCliReaders = {
     surface: flags.surface,
     activity: flags.activity,
     launchConsole: flags.launchConsole,
+    launchArgs: flags.launchArgs,
     relaunch: flags.relaunch,
     saveScript: flags.saveScript,
     noRecord: flags.noRecord,
diff --git a/src/commands/client-command-contracts.ts b/src/commands/client-command-contracts.ts
@@ -81,6 +81,7 @@ export const clientCommandDefinitions = [
       surface: enumField(SURFACE_VALUES),
       activity: stringField('Android activity name.'),
       launchConsole: stringField('Launch console mode.'),
+      launchArgs: stringArrayField('iOS launch arguments forwarded verbatim to the app process.'),
       relaunch: booleanField('Force relaunch.'),
       saveScript: jsonSchemaField<boolean | string>({ oneOf: [booleanSchema(), stringSchema()] }),
       noRecord: booleanField('Do not record this action.'),
diff --git a/src/daemon-client.ts b/src/daemon-client.ts
@@ -55,6 +55,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;
@@ -213,6 +214,7 @@ export async function openApp(options: OpenAppOptions = {}): Promise<DaemonRespo
     serial,
     activity,
     launchConsole,
+    launchArgs,
     out,
     saveScript,
     relaunch,
@@ -234,6 +236,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 } : {}),
diff --git a/src/daemon/handlers/__tests__/session-open-runtime.test.ts b/src/daemon/handlers/__tests__/session-open-runtime.test.ts
@@ -146,13 +146,14 @@ test('open applies stored runtime launchUrl and reports runtime hints', async ()
   }
 });
 
-test('open applies launchConsole only to the direct app launch before runtime launchUrl', async () => {
+test('open applies launch-only flags only to the direct app launch before runtime launchUrl', async () => {
   const sessionStore = makeSessionStore();
   const launchConsolePath = path.join(os.tmpdir(), 'launch-console.log');
   const dispatchCalls: Array<{
     command: string;
     positionals: string[];
     launchConsole?: string;
+    launchArgs?: string[];
   }> = [];
 
   sessionStore.setRuntimeHints('launch-console-runtime', {
@@ -167,7 +168,12 @@ test('open applies launchConsole only to the direct app launch before runtime la
     booted: true,
   });
   mockDispatch.mockImplementation(async (_device, command, positionals, _outPath, context) => {
-    dispatchCalls.push({ command, positionals, launchConsole: context?.launchConsole });
+    dispatchCalls.push({
+      command,
+      positionals,
+      launchConsole: context?.launchConsole,
+      launchArgs: context?.launchArgs,
+    });
     return {};
   });
 
@@ -177,7 +183,7 @@ test('open applies launchConsole only to the direct app launch before runtime la
       session: 'launch-console-runtime',
       command: 'open',
       positionals: ['Demo'],
-      flags: { platform: 'ios', launchConsole: launchConsolePath },
+      flags: { platform: 'ios', launchConsole: launchConsolePath, launchArgs: ['-Flag', 'YES'] },
     },
     sessionName: 'launch-console-runtime',
     logPath: path.join(os.tmpdir(), 'daemon.log'),
@@ -187,8 +193,18 @@ test('open applies launchConsole only to the direct app launch before runtime la
 
   expect(response?.ok).toBe(true);
   expect(dispatchCalls).toEqual([
-    { command: 'open', positionals: ['Demo'], launchConsole: launchConsolePath },
-    { command: 'open', positionals: ['myapp://dev-client'], launchConsole: undefined },
+    {
+      command: 'open',
+      positionals: ['Demo'],
+      launchConsole: launchConsolePath,
+      launchArgs: ['-Flag', 'YES'],
+    },
+    {
+      command: 'open',
+      positionals: ['myapp://dev-client'],
+      launchConsole: undefined,
+      launchArgs: undefined,
+    },
   ]);
 });
 
diff --git a/src/daemon/handlers/session-open.ts b/src/daemon/handlers/session-open.ts
@@ -91,6 +91,7 @@ function contextForRuntimeLaunchUrl(
 ): ReturnType<typeof contextFromFlags> {
   const context = contextFromFlags(logPath, flags, appBundleId, traceLogPath);
   delete context.launchConsole;
+  delete context.launchArgs;
   return context;
 }
 
diff --git a/src/platforms/ios/__tests__/index.test.ts b/src/platforms/ios/__tests__/index.test.ts
@@ -926,6 +926,177 @@ test('openIosApp captures iOS simulator launch console output when requested', a
   }
 });
 
+test('openIosApp emits a clean simctl launch when launchArgs is an empty array', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-launch-args-empty-'));
+  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;
+
+  try {
+    mockEnsureBootedSimulator.mockResolvedValue();
+    await openIosApp(IOS_TEST_SIMULATOR, 'MyApp', {
+      appBundleId: 'com.example.app',
+      launchArgs: [],
+    });
+    const args = (await fs.readFile(argsLogPath, 'utf8')).trim().split('\n').filter(Boolean);
+    assert.deepEqual(args, ['simctl', 'launch', 'sim-1', 'com.example.app']);
+  } 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 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;
+
+  try {
+    await openIosApp(IOS_TEST_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;
+
+  try {
+    await openIosApp(IOS_TEST_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),
diff --git a/src/platforms/ios/apps.ts b/src/platforms/ios/apps.ts
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
diff --git a/src/utils/__tests__/daemon-client.test.ts b/src/utils/__tests__/daemon-client.test.ts
diff --git a/src/utils/cli-command-overrides.ts b/src/utils/cli-command-overrides.ts
diff --git a/src/utils/cli-flags.ts b/src/utils/cli-flags.ts
