Mason Docs

Mason Platform CLI Version 1

The Mason CLI provides command line tools to help you manage and configure your devices in the Mason Platform.

Typical uses for the Platform CLI include and are not limited to

  • Integrating Mason OS deployments and updates in your CI/CD pipelines
  • A/B testing different versions of your app on different Mason devices
  • Configuring different versions of Mason OS for your devices
  • ...and more!

This is our old CLI release. To use the latest release, please visit the current Mason CLI's documentation. Mason CLI version 2.0+ is needed for using X-Ray if the device is running Mason OS 6.0.6+.

Install

Visit our installation guide to get the CLI up and running on your platform

CLI Commands

mason help

The mason help command displays information about the Mason CLI.

The --help option can be combined with any command to get a detailed explanation of how to use it.

Variants

mason help
mason help [COMMAND]
mason [COMMAND] --help

mason -v debug

The Mason CLI has a built-in debugging utility, in case you get stuck or encounter unexpected issues.

Run any command with -v debug to get more information.

Variants

mason -v debug [COMMAND]

Usage

mason -v debug login

mason login

The login command authenticates you with the Mason Platform.

Your session will be valid for 24 hours. If you'd like to end your session earlier than that, run mason logout.

when logging in, you can supply an API key using the --api-key option

Variants

mason login
mason login --api-key [APIKEY]

mason logout

Logs you out of a running session. This command can be useful for security purposes.

Variants

mason logout

mason init

The init command automatically configures a .masonrc file for the mason register project command.

The .masonrc file tells the CLI where to find your Project configurations, APKs, and media.

The rc file is a JSON config, and can be manually configured as follows:

// Note: all fields support either a single object or a list of objects.
{
  // The "configs" field is optional and defaults to "mason.yml".
  "configs": "project.yml",
  // The "apps" field takes a file or folder pointing to APKs.
  "apps": [
    "path/to/apk/name.apk",
    "built-apks"
  ],
  // The "bootanimations" field takes an object with the animation name used in your OS config and
  // the ZIP's file path.
  "bootanimations": {
    "name": "anim-name",
    "file": "anims/bootanimation.zip"
  },
  // The "splashes" field takes an object with the splash name used in your OS config and
  // the image's file path.
  "splashes": {
    "name": "splash-name",
    "file": "splash.png"
  }
}

Variants

mason init
mason init [FILEPATH]

mason register

The register command lets you upload artifacts to be deployed later to the Mason Platform.

The following artifacts can be registered

mason register project

If you have run mason init in your project, you can use this command.

If you are using this command to register a project, you can leave out the app and media version codes in the project config, the CLI will auto-increment the versions for you.

For more information, visit our guide for creating projects

Variants

mason register project [CONTEXT]

mason register apk

The register apk command lets you upload APKs to the Mason Platform.

Before you register an APK, you must ensure that it is signed with a non-debug signing key.

You must use this certificate for all future versions of this APK

When registering new versions of existing APKs, you must ensure that the versionCode does not match another version that already exists in the Mason Platform.

Variants

mason register apk [APKS...]

mason register media

The register media command lets you upload media artifactsto the Mason Platform.

The following media types can be registered

you can use the latest keyword in place of the version number, and the Mason CLI will auto-increment the version number when you re-register existing media

mason register media bootanimation

The register media bootanimation command lets you upload boot animation artifacts.

Variants

mason register media bootanimation [NAME] [VERSION] [MEDIA]

mason register media splash

The register media splash command lets you upload splash screen artifacts to the Mason Platform.

Variants

mason register media splash [NAME] [VERSION] [MEDIA]

mason register config

The register config command lets you upload a single Mason OS configuration to the Mason Platform.

Variants

mason register config [CONFIGS...]

mason deploy

The mason deploy command lets you remotely push Mason OS and APK updates to device groups.

The following deployable artifacts are:

By default, the artifacts won't be installed until each device checks-in to the Mason Platform, which could take a non-deterministic amount of time.

You can use the --push option when using mason deploy in order to immediately push artifacts to a device group, rather than wait for the device to check-in

Variants

mason deploy [OPTIONS]
mason deploy --push [OPTIONS]

mason deploy apk

The deploy apk command lets you push an APK to a device group directly without going through the lifecycle of deploying a complete Mason OS configuration.

deploying an APK using mason deploy apk will not add the APK to your Mason OS configuration

In order for an APK deployment to be successful, you must provide a name, version, and group to deploy to.

If you would like to deploy the highest version of the given APK, use the latest keyword in place of the version number

Variants

mason deploy apk [NAME] [VERSION] [GROUP]
mason deploy apk [NAME] latest [GROUP]

mason deploy config

The deploy config command lets you deploy an Mason OS configuration to a device group.

when you push a new Mason OS configuration to a device group, each device in that group must download the update and do a full reboot in order for the changes to take effect

In order for a Mason OS configuration deployment to be successful, you must provide a name, version, and group to deploy to.

If you would like to deploy the highest version of the given config, use the latest keyword in place of the version number

Variants

mason deploy config [NAME] [VERSION] [GROUP]
mason deploy config [NAME] latest [GROUP]
mason deploy config [NAME] [VERSION] [GROUPS...]

mason deploy ota

The deploy ota command lets you update the Mason Android version that is running on the device.

  • NAME of the ota to be deployed. Valid values: mason-os
  • VERSION of the ota
  • GROUP(S) to deploy the ota

Variants

mason deploy ota [NAME] [VERSION] [GROUPS...]

mason xray

The xray command allows you to interact with your devices remotely.

Need help getting started? Visit our guide on setting up xray

mason xray logcat

The xray logcat command streams logs from the device to your terminal.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray logcat to succeed, you must supply a deviceId, and (optionally) any valid logcat arguments

Learn more about available logcat arguments here: https://d.android.com/studio/command-line/logcat.

Variants

mason xray [DEVICEID] logcat
mason xray [DEVICEID] logcat [ARGUMENTS]

mason xray shell

The xray shell command opens an interactive shell on the device.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray shell to succeed, you must supply a deviceId, and any valid shell arguments

Learn more about available shell arguments here: https://developer.android.com/studio/command-line/shell.

Variants

mason xray shell [DEVICEID] shell [ARGUMENTS]

Usage

$ mason xray $DEVICE_ID shell ls /sdcard
  ...

$ mason xray $DEVICE_ID shell cat my-file.txt
  ...

mason xray push

The xray push command copies files to the device.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray push to succeed, you must supply a deviceId, a src filepath on your machine, a dest filepath on the device to push to.

By default, the remote path starts at the root of the device's file system. However, it will try to use the device's home directory where appropriate

Variants

mason xray [DEVICEID] push [SRC] [DEST]

mason xray pull

The xray pull command copies files from the device.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray pull to succeed, you must supply a deviceId, and a filepath to pull from.

By default, the remote path starts at the root of the device's file system. However, it will try to use the device's home directory where appropriate

Variants

mason xray [DEVICEID] pull [FILEPATH]

mason xray install

The xray install command installs an APK on a device.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray install to succeed, you must supply a deviceId, and an apk to uninstall

Variants

mason xray [DEVICEID] install [APK]

mason xray uninstall

The xray uninstall command uninstalls an APK on a device.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for mason xray uninstall to succeed, you must supply a deviceId, and an apk to uninstall

Variants

mason xray [DEVICEID] uninstall [APK]

mason xray adbproxy

The xray adbproxy command provides support for generic adb commands.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

Once the xray adbproxy command succeeds, you can run adb connect localhost:$PORT to then execute *any- adb commands.

In order for mason xray adbproxy to succeed, you must supply a deviceId.

You can specify a port using the -p [PORT] command

Variants

mason xray [DEVICEID] adbproxy
mason xray [DEVICEID] adbproxy -p [PORT]

Usage

mason xray $DEVICE_ID adbproxy -p 5555
...

adb connect localhost:5555
adb logcat
...

mason xray bugreport

The mason xray bugreport command captures a bug report from the device and saves the file to your current directory.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for a screencap to succeed, you must supply a deviceId.

Variants

mason xray [DEVICEID] bugreport

mason xray screencap

The mason screencap command captures a screenshot from the device and saves the screenshot to your current directory.

this command requires an API Key with the permission FLEET:ADMIN to be configured in the Mason CLI. Visit our guide for configuring an API Key with the Mason CLI if you need help with this.

In order for a screencap to succeed, you must supply a deviceId.

you can give the Mason CLI a name for the screenshot using -o [NAME]

Variants

mason xray [DEVICEID] screencap
mason xray [DEVICEID] screencap -o [NAME]

Need help?