thymikee · Sep 14, 2026 · Sep 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,10 @@
   "Untitled Project" / "Untitled Build" with an empty name — even after #2495 carried the flags to
   the provider (#2494). The builder now emits `appium:deviceName`, `appium:platformVersion`, and
   `appium:app` and no legacy key, verified against live App Automate sessions.
+- Added: `--provider-appium-version <version>` (alias `--appium-version`) pins the Appium server
+  BrowserStack runs for the session, as `bstack:options.appiumVersion`. Unset, BrowserStack falls
+  back to Appium 1.x, which predates the `mobile:` commands the interactor issues (`deepLink`,
+  `pressButton`, `activateApp`).
 - Changed (sessions): the implicit session is now keyed by workspace **and platform**, so one checkout
   can drive iOS and Android without inventing a `--session` name for every command (#2580). An
   implicit session was addressed by `cwd:<workspace>:default`, one slot per checkout, and it stayed

diff --git a/packages/command-registry/src/flag-definitions-connection.ts b/packages/command-registry/src/flag-definitions-connection.ts
@@ -230,6 +230,16 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     projectConfig: false,
     recorded: false,
   },
+  {
+    key: 'providerAppiumVersion',
+    names: ['--provider-appium-version', '--appium-version'],
+    type: 'string',
+    usageLabel: '--provider-appium-version <version>',
+    usageDescription:
+      'Hosted cloud provider Appium server version, for example 3.2.0. Without it BrowserStack falls back to its default (Appium 1.x)',
+    projectConfig: false,
+    recorded: false,
+  },
   {
     key: 'providerLanguage',
     names: ['--provider-language', '--language'],

diff --git a/packages/command-registry/src/flag-groups.ts b/packages/command-registry/src/flag-groups.ts
@@ -82,6 +82,7 @@ export const COMMON_COMMAND_SUPPORTED_FLAG_KEYS = flagKeys(
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',

diff --git a/packages/contracts/src/client-connection.ts b/packages/contracts/src/client-connection.ts
@@ -69,6 +69,7 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'providerDeviceOrientation'
   | 'providerGeoLocation'
   | 'providerTimezone'
+  | 'providerAppiumVersion'
   | 'providerLanguage'
   | 'providerLocale'
   | 'providerNetworkProfile'

diff --git a/packages/contracts/src/lease-scope.ts b/packages/contracts/src/lease-scope.ts
@@ -219,6 +219,7 @@ const LEASE_ALLOCATE_PROVIDER_FLAG_KEYS = [
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',

diff --git a/packages/contracts/src/remote-config-fields.ts b/packages/contracts/src/remote-config-fields.ts
@@ -29,6 +29,7 @@ export type CloudProviderProfileFields = {
   providerDeviceOrientation?: ProviderDeviceOrientation;
   providerGeoLocation?: string;
   providerTimezone?: string;
+  providerAppiumVersion?: string;
   providerLanguage?: string;
   providerLocale?: string;
   providerNetworkProfile?: string;

diff --git a/packages/provider-webdriver/src/browserstack-device-features.test.ts b/packages/provider-webdriver/src/browserstack-device-features.test.ts
@@ -14,6 +14,7 @@ const DEVICE_FEATURE_FIELDS = [
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',
@@ -34,6 +35,7 @@ test('configured device features project onto BrowserStack vendor capability key
       providerDeviceOrientation: 'portrait',
       providerGeoLocation: 'US',
       providerTimezone: 'New_York',
+      providerAppiumVersion: '3.2.0',
       providerLanguage: 'Fr',
       providerLocale: 'Fr',
       providerNetworkProfile: '4g-lte-advanced-good',
@@ -46,6 +48,7 @@ test('configured device features project onto BrowserStack vendor capability key
     deviceOrientation: 'portrait',
     geoLocation: 'US',
     timezone: 'New_York',
+    appiumVersion: '3.2.0',
     language: 'Fr',
     locale: 'Fr',
     networkProfile: '4g-lte-advanced-good',

diff --git a/packages/provider-webdriver/src/browserstack-device-features.ts b/packages/provider-webdriver/src/browserstack-device-features.ts
@@ -20,6 +20,7 @@ export type BrowserStackDeviceFeatureFields = Pick<
   | 'providerDeviceOrientation'
   | 'providerGeoLocation'
   | 'providerTimezone'
+  | 'providerAppiumVersion'
   | 'providerLanguage'
   | 'providerLocale'
   | 'providerNetworkProfile'
@@ -64,6 +65,14 @@ export const BROWSERSTACK_DEVICE_FEATURE_SPECS: readonly BrowserStackDeviceFeatu
     flag: '--provider-timezone',
     type: 'string',
   },
+  {
+    // BrowserStack defaults to Appium 1.x when unset; `mobile:` commands the interactor issues
+    // (deepLink, pressButton, activateApp) need a 2.x+ server.
+    field: 'providerAppiumVersion',
+    capability: 'appiumVersion',
+    flag: '--provider-appium-version',
+    type: 'string',
+  },
   {
     field: 'providerLanguage',
     capability: 'language',

diff --git a/scripts/integration-progress-model.ts b/scripts/integration-progress-model.ts
@@ -259,6 +259,7 @@ function summarizeProviderScenarioFlagExclusions() {
         'providerDeviceOrientation',
         'providerGeoLocation',
         'providerTimezone',
+        'providerAppiumVersion',
         'providerLanguage',
         'providerLocale',
         'providerNetworkProfile',

diff --git a/src/cli-schema/command-overrides.ts b/src/cli-schema/command-overrides.ts
@@ -83,6 +83,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
       'providerDeviceOrientation',
       'providerGeoLocation',
       'providerTimezone',
+      'providerAppiumVersion',
       'providerLanguage',
       'providerLocale',
       'providerNetworkProfile',

diff --git a/src/cli.ts b/src/cli.ts
@@ -462,6 +462,7 @@ function buildClientConfig(ctx: CliRunContext): AgentDeviceClientConfig {
     providerDeviceOrientation: currentFlags.providerDeviceOrientation,
     providerGeoLocation: currentFlags.providerGeoLocation,
     providerTimezone: currentFlags.providerTimezone,
+    providerAppiumVersion: currentFlags.providerAppiumVersion,
     providerLanguage: currentFlags.providerLanguage,
     providerLocale: currentFlags.providerLocale,
     providerNetworkProfile: currentFlags.providerNetworkProfile,

diff --git a/src/cli/connection/profile-fields.ts b/src/cli/connection/profile-fields.ts
@@ -16,6 +16,7 @@ export function readCloudDeviceFeatureProfileFields(
   | 'providerDeviceOrientation'
   | 'providerGeoLocation'
   | 'providerTimezone'
+  | 'providerAppiumVersion'
   | 'providerLanguage'
   | 'providerLocale'
   | 'providerNetworkProfile'
@@ -26,6 +27,7 @@ export function readCloudDeviceFeatureProfileFields(
     providerDeviceOrientation: flags.providerDeviceOrientation,
     providerGeoLocation: flags.providerGeoLocation,
     providerTimezone: flags.providerTimezone,
+    providerAppiumVersion: flags.providerAppiumVersion,
     providerLanguage: flags.providerLanguage,
     providerLocale: flags.providerLocale,
     providerNetworkProfile: flags.providerNetworkProfile,

diff --git a/src/cli/parser/__tests__/args-parse-session.test.ts b/src/cli/parser/__tests__/args-parse-session.test.ts
@@ -745,12 +745,15 @@ test('parseArgs recognizes connect device-feature flags and their short aliases'
       '--network-profile',
       '4g-lte-advanced-good',
       '--provider-no-resign-app',
+      '--appium-version',
+      '3.2.0',
     ],
     { strictFlags: true },
   );
   assert.equal(parsed.flags.providerDeviceOrientation, 'portrait');
   assert.equal(parsed.flags.providerGeoLocation, 'US');
   assert.equal(parsed.flags.providerTimezone, 'New_York');
+  assert.equal(parsed.flags.providerAppiumVersion, '3.2.0');
   assert.equal(parsed.flags.providerLanguage, 'Fr');
   assert.equal(parsed.flags.providerLocale, 'Fr');
   assert.equal(parsed.flags.providerNetworkProfile, '4g-lte-advanced-good');

diff --git a/src/commands/command-flags.ts b/src/commands/command-flags.ts
@@ -35,6 +35,7 @@ function buildFlags(options: InternalRequestOptions): CommandFlags {
     providerDeviceOrientation: options.providerDeviceOrientation,
     providerGeoLocation: options.providerGeoLocation,
     providerTimezone: options.providerTimezone,
+    providerAppiumVersion: options.providerAppiumVersion,
     providerLanguage: options.providerLanguage,
     providerLocale: options.providerLocale,
     providerNetworkProfile: options.providerNetworkProfile,

diff --git a/src/daemon/handlers/session-doctor-options.ts b/src/daemon/handlers/session-doctor-options.ts
@@ -26,6 +26,7 @@ const REMOTE_PROVIDER_FLAG_KEYS = [
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',

diff --git a/src/remote/remote-config-schema.ts b/src/remote/remote-config-schema.ts
@@ -88,6 +88,7 @@ export const REMOTE_CONFIG_FIELD_SPECS = [
   },
   { key: 'providerGeoLocation', type: 'string' },
   { key: 'providerTimezone', type: 'string' },
+  { key: 'providerAppiumVersion', type: 'string' },
   { key: 'providerLanguage', type: 'string' },
   { key: 'providerLocale', type: 'string' },
   { key: 'providerNetworkProfile', type: 'string' },

diff --git a/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts b/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts
@@ -105,6 +105,7 @@ test('BrowserStack facade nests device-feature capabilities inside bstack:option
           providerDeviceOrientation: 'portrait',
           providerGeoLocation: 'US',
           providerTimezone: 'New_York',
+          providerAppiumVersion: '3.2.0',
           providerLanguage: 'Fr',
           providerLocale: 'Fr',
           providerNetworkProfile: '4g-lte-advanced-good',
@@ -127,6 +128,7 @@ test('BrowserStack facade nests device-feature capabilities inside bstack:option
       deviceOrientation: 'portrait',
       geoLocation: 'US',
       timezone: 'New_York',
+      appiumVersion: '3.2.0',
       language: 'Fr',
       locale: 'Fr',
       networkProfile: '4g-lte-advanced-good',

diff --git a/website/docs/docs/browserstack.md b/website/docs/docs/browserstack.md
@@ -44,6 +44,7 @@ Optional device features:
 --provider-device-orientation portrait   # or landscape        (alias --device-orientation)
 --provider-geo-location US                                   # (alias --geo-location)
 --provider-timezone New_York                                 # (alias --timezone)
+--provider-appium-version 3.2.0                              # (alias --appium-version)
 --provider-language Fr                                       # (alias --language)
 --provider-locale Fr                                         # (alias --locale)
 --provider-network-profile 4g-lte-advanced-good              # (alias --network-profile)
@@ -54,6 +55,7 @@ Optional device features:
 BrowserStack receives these values in `bstack:options` when it creates the hosted session.
 
 - The orientation applies when the session starts. An activity without a fixed orientation, such as a Chrome Custom Tab hosting OAuth, can still open in landscape. Run `agent-device orientation portrait` after launching it when needed.
+- `--provider-appium-version` pins the Appium server BrowserStack runs for the session. Unset, BrowserStack falls back to its default Appium 1.x; `mobile:` commands such as `deepLink` and `pressButton` need a 2.x or newer server.
 - `--provider-network-profile` and `--provider-custom-network` are mutually exclusive.
 - `--provider-no-resign-app` applies to iOS only. BrowserStack re-signs uploaded iOS apps with its provisioning profile, which strips entitlements; opt out when testing entitlement-dependent features such as push notifications.