feat(android): pass apps launch --arg key=value as string intent extras

Each --arg on Android must be key=value and becomes am start --es key
value, which the app reads from its launch intent. An argument without
'=' is an error. --env stays iOS-only.

Author: mobile-kevin

README.md

@@ -245,9 +245,12 @@ mobilecli apps foreground --device <device-id>
 # Launch an app
 mobilecli apps launch <bundle-id> --device <device-id>
 
-# Launch an app with arguments and environment variables (iOS only)
+# Launch an app with arguments and environment variables (iOS)
 mobilecli apps launch <bundle-id> --device <device-id> --arg -FeatureX --arg YES --env API_URL=https://staging.example.com
 
+# Launch an app with string intent extras (Android, each --arg is key=value and becomes --es key value)
+mobilecli apps launch <package-name> --device <device-id> --arg featureX=true --arg apiUrl=https://staging.example.com
+
 # Terminate an app
 mobilecli apps terminate <bundle-id> --device <device-id>
 

cli/apps.go

@@ -190,7 +190,7 @@ func init() {
 	appsLaunchCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to launch app on")
 	appsLaunchCmd.Flags().StringVar(&locale, "locale", "", "Comma-separated BCP 47 locale tags (e.g., fr-FR,en-GB)")
 	appsLaunchCmd.Flags().StringVar(&activity, "activity", "", "Android activity to launch (e.g. .DebugActivity or com.example/.DebugActivity)")
-	appsLaunchCmd.Flags().StringArrayVar(&launchArgs, "arg", nil, "Argument to pass to the app, repeat for more (iOS only)")
+	appsLaunchCmd.Flags().StringArrayVar(&launchArgs, "arg", nil, "Argument to pass to the app, repeat for more. On Android it must be key=value and is passed as a string intent extra")
 	appsLaunchCmd.Flags().StringArrayVar(&launchEnv, "env", nil, "Environment variable KEY=VALUE to set for the app, repeat for more (iOS only)")
 	appsTerminateCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to terminate app on")
 	appsListCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to list apps from")

devices/android.go

@@ -478,8 +478,9 @@ func (d *AndroidDevice) resolveLauncherActivity(bundleID string) (string, error)
 }
 
 func (d *AndroidDevice) LaunchApp(bundleID string, opts LaunchOptions) error {
-	if len(opts.Arguments) > 0 {
-		return fmt.Errorf("--arg is not supported on Android")
+	extras, err := launchExtras(opts.Arguments)
+	if err != nil {
+		return err
 	}
 	if len(opts.Env) > 0 {
 		return fmt.Errorf("--env is not supported on Android")
@@ -499,7 +500,6 @@ func (d *AndroidDevice) LaunchApp(bundleID string, opts LaunchOptions) error {
 	}
 
 	var component string
-	var err error
 	if opts.Activity != "" {
 		component, err = buildLaunchComponent(bundleID, opts.Activity)
 	} else {
@@ -509,7 +509,7 @@ func (d *AndroidDevice) LaunchApp(bundleID string, opts LaunchOptions) error {
 		return err
 	}
 
-	output, err := d.runAdbShell(launchArgs(component, d.isAppRunning(bundleID))...)
+	output, err := d.runAdbShell(launchArgs(component, d.isAppRunning(bundleID), extras)...)
 	if err != nil {
 		return fmt.Errorf("failed to launch app %s: %w\nOutput: %s", bundleID, err, string(output))
 	}
@@ -522,14 +522,30 @@ func (d *AndroidDevice) LaunchApp(bundleID string, opts LaunchOptions) error {
 // permission prompt, stays on top: a plain start just resumes it. When the app isn't
 // running, clear the task so the launch shows the app. When it is running, keep the
 // task so launching brings the app to the front as it was.
-func launchArgs(component string, isRunning bool) []string {
+func launchArgs(component string, isRunning bool, extras []string) []string {
 	args := []string{"am", "start", "--display", defaultDisplayID}
 	if !isRunning {
 		args = append(args, "--activity-clear-task")
 	}
+	args = append(args, extras...)
 	return append(args, "-n", component)
 }
 
+// launchExtras turns key=value launch arguments into `am start --es key value`
+// string extras, which the app reads from its launch intent. The value may
+// contain '=' and may be empty.
+func launchExtras(arguments []string) ([]string, error) {
+	extras := make([]string, 0, len(arguments)*3)
+	for _, argument := range arguments {
+		key, value, found := strings.Cut(argument, "=")
+		if !found || key == "" {
+			return nil, fmt.Errorf("invalid --arg %q, on Android each argument must be key=value", argument)
+		}
+		extras = append(extras, "--es", key, value)
+	}
+	return extras, nil
+}
+
 // isAppRunning reports whether the package has a live process. pidof exits non-zero
 // when there is none.
 func (d *AndroidDevice) isAppRunning(bundleID string) bool {

devices/android_launch_test.go

@@ -140,17 +140,42 @@ func Test_adbShellArgs_keepsEveryQueryParameterOfAURL(t *testing.T) {
 }
 
 func Test_launchArgs_clearsTheTaskWhenTheAppIsNotRunning(t *testing.T) {
-	got := strings.Join(launchArgs("com.example/.Main", false), " ")
+	got := strings.Join(launchArgs("com.example/.Main", false, nil), " ")
 	want := "am start --display " + defaultDisplayID + " --activity-clear-task -n com.example/.Main"
 	if got != want {
 		t.Fatalf("launchArgs() = %q, want %q", got, want)
 	}
 }
 
 func Test_launchArgs_keepsTheTaskWhenTheAppIsRunning(t *testing.T) {
-	got := strings.Join(launchArgs("com.example/.Main", true), " ")
+	got := strings.Join(launchArgs("com.example/.Main", true, nil), " ")
 	want := "am start --display " + defaultDisplayID + " -n com.example/.Main"
 	if got != want {
 		t.Fatalf("launchArgs() = %q, want %q", got, want)
 	}
 }
+
+func Test_launchArgs_passesExtrasBeforeTheComponent(t *testing.T) {
+	got := strings.Join(launchArgs("com.example/.Main", true, []string{"--es", "flag", "on"}), " ")
+	want := "am start --display " + defaultDisplayID + " --es flag on -n com.example/.Main"
+	if got != want {
+		t.Fatalf("launchArgs() = %q, want %q", got, want)
+	}
+}
+
+func Test_launchExtras(t *testing.T) {
+	got, err := launchExtras([]string{"apiUrl=https://x.test/?a=b", "empty="})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := "--es apiUrl https://x.test/?a=b --es empty "
+	if strings.Join(got, " ") != want {
+		t.Errorf("launchExtras() = %q, want %q", strings.Join(got, " "), want)
+	}
+
+	for _, bad := range []string{"-FeatureX", "=value"} {
+		if _, err := launchExtras([]string{bad}); err == nil {
+			t.Errorf("launchExtras(%q): expected error, got nil", bad)
+		}
+	}
+}

devices/common.go

@@ -153,7 +153,9 @@ type FileEntry struct {
 
 // LaunchOptions carries optional parameters for launching an app.
 // Activity is Android-only; passing it to an iOS device is an error.
-// Arguments and Env are iOS-only; passing them to an Android device is an error.
+// Arguments are process arguments on iOS. On Android each one must be key=value
+// and is passed as a string intent extra. Env is iOS-only; passing it to an
+// Android device is an error.
 type LaunchOptions struct {
 	Locales   []string
 	Activity  string

devices/simulator_launch_test.go

@@ -50,11 +50,11 @@ func Test_simctlLaunchEnv(t *testing.T) {
 	}
 }
 
-func Test_LaunchApp_ArgumentsAndEnvRejectedOnAndroid(t *testing.T) {
+func Test_LaunchApp_EnvAndBareArgumentsRejectedOnAndroid(t *testing.T) {
 	device := &AndroidDevice{}
 
-	if err := device.LaunchApp("com.example.app", LaunchOptions{Arguments: []string{"-x"}}); err == nil {
-		t.Fatal("expected error for arguments, got nil")
+	if err := device.LaunchApp("com.example.app", LaunchOptions{Arguments: []string{"-FeatureX"}}); err == nil {
+		t.Fatal("expected error for an argument without '=', got nil")
 	}
 
 	if err := device.LaunchApp("com.example.app", LaunchOptions{Env: map[string]string{"A": "1"}}); err == nil {

skills/mobilecli/reference.md

@@ -51,8 +51,10 @@ All commands support the global `--device <id>` flag to specify the target devic
 * **Launch / Terminate**:
   ```bash
   mobilecli apps launch <bundle-id> --device <device-id>
-  # iOS only: repeat --arg and --env as needed
+  # iOS: repeat --arg and --env as needed
   mobilecli apps launch <bundle-id> --device <device-id> --arg -FeatureX --arg YES --env API_URL=https://staging.example.com
+  # Android: each --arg is key=value and is passed as a string intent extra (--es key value)
+  mobilecli apps launch <package-name> --device <device-id> --arg featureX=true
   mobilecli apps terminate <bundle-id> --device <device-id>
   ```
 * **Install / Uninstall**: