Opening and resetting the app

The commands that open the app do so by simulating the app's launch as if the user tapped on the app icon on the phone; these are:

• enroll
• unenroll
• test-feature
• apply-file
• log-state
• open.

In addition, the enroll, open and test-feature commands, can launch the app with a deeplink.

Deeplinking

nimbus-cli knows the apps' deeplinking schemes, and if no :// is detected in the deeplink, then the deeplink scheme is appended.

open

For example:

nimbus-cli --app firefox_ios --channel developer open

launches the app with simctl:

$ xcrun simctl launch \
        booted \
        org.mozilla.ios.Fennec \
        --nimbus-cli \
        --version \
        1

nimbus-cli --app firefox_ios --channel developer open --deeplink deep-link?url=settings/general

opens the deeplink (i.e. not sending directly to the app) with:

$ xcrun simctl openurl \
        booted \
        fennec://deep-link?url=settings/general

By default, each of the commands that launches the app also kills the app right before; with the open command you can send the app a deeplink without killing it, using the --no-clobber property.

nimbus-cli --app firefox_ios --channel developer enroll ios-set-to-default-in-onboarding-final --branch treatment-a
nimbus-cli --app firefox_ios --channel developer open --deeplink deep-link?url=onboarding/privacy-first --no-clobber

Deeplinks for other commands:

iOS simctl does not support command line arguments with the openurl command, and only supports a URL length of 2047.

Opening with a deeplink while enrolling in an experiment is supported but requires a different route. See Working with Devices.

enroll

For Android, opening a deeplink uses the same mechanism as launching the app: using Intents. Thus, we can enroll in an experiment and then open the app with a deeplink.

nimbus-cli --app fenix --channel developer enroll release-android-onboarding-redesign --branch treatment-a --deeplink onboarding/privacy-first

test-feature

Similarly, you can use a --deeplink to enroll a test-feature experiment.

Terminating and Resetting the app

open, enroll and test-feature all support a --reset-app option, which serves to reset the app back to its just-installed state before opening.

Passthrough parameters

Opening apps with nimbus-cli provides an abstraction over adb shell start am and xcrun simctl launch.

Passthrough parameters offer a small escape hatch from this abstraction.

Trailing parameters for apps

You may want to send additional command line parameters to these commands. You can do this by appending them with -- after the open, enroll, or test-feature commands:

nimbus-cli --app firefox_ios --channel developer open --reset-app -- FIREFOX_TEST FIREFOX_SKIP_INTRO

This produces an xcrun command:

$ xcrun simctl launch \
        booted \
        org.mozilla.ios.Fennec \
        FIREFOX_TEST \
        FIREFOX_SKIP_INTRO

These are entirely app specific. e.g. Firefox for iOS has the launch parameters available in LaunchArguments.swift.

For Android apps, you can modify the intent being sent to the device with intent arguments. The most saliant are reproduced here:

Extra parameters	Description
--esn extra_key	Add a null extra. This option is not supported for URI intents.
--es extra_key extra_string_value	Add string data as a key-value pair.
--ez extra_key extra_boolean_value	Add boolean data as a key-value pair.
--ei extra_key extra_int_value	Add integer data as a key-value pair.
--el extra_key extra_long_value	Add long data as a key-value pair.

For a fictional example:

nimbus-cli --app fenix --channel developer open --reset-app -- --esn SKIP_INTRO

produces an adb command:

$ adb shell "am start -n org.mozilla.fenix.debug/.App \
        -a android.intent.action.MAIN \
        -c android.intent.category.LAUNCHER \
        --esn \
        SKIP_INTRO"

Leading parameters

For finer control of xcrun and adb, you can use {} as a positional indicator:

For example, to enable debugging, you need to pass the -D parameter:

nimbus-cli --app fenix --channel developer open -- -D {}

This produces an adb command:

 adb shell "am start -D \
        -n org.mozilla.fenix.debug/.App \
        -a android.intent.action.MAIN \
        -c android.intent.category.LAUNCHER"

Leading and trailing parameters can be combined, and used with any combination of open, test-feature and enroll.

nimbus-cli --app firefox_ios --channel developer \
        enroll ios-search-bar-placement-v2-treatment-a-rollout --branch treatment-a \
        -- \
        --console-pty {} FIREFOX_SKIP_INTRO

Platform specific passthrough parameters

Leading parameters are platform specific:

adb shell am can be configured with:

• -D: Enable debugging.
• -W: Wait for launch to complete.
• --start-profiler file: Start profiler and send results to file.
• -P file: Like --start-profiler, but profiling stops when the app goes idle.
• -R count: Repeat the activity launch count times. Prior to each repeat, the top activity will be finished.
• -S: Force stop the target app before starting the activity.
• --opengl-trace: Enable tracing of OpenGL functions.
• --user user_id | current: Specify which user to run as; if not specified, then run as the current user.

xcrun simctl launch can be configured with:

• --console Block and print the application's stdout and stderr to the current terminal. Signals received by simctl are passed through to the application. (Cannot be combined with --stdout or --stderr)
• --console-pty Block and print the application's stdout and stderr to the current terminal via a PTY. Signals received by simctl are passed through to the application. (Cannot be combined with --stdout or --stderr)
• --stdout=<path> Redirect the application's standard output to a file.
• --stderr=<path> Redirect the application's standard error to a file.
• --terminate-running-process Terminate any running copy of the application. Note: Log output is often directed to stderr, not stdout.