Mason CLI

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

Installing the CLI

To manually download the CLI binary, visit the latest release. Under the “Assets” section, download the variant of the CLI for your platform.

Windows

  1. Follow the instructions above to download the mason.exe file
  2. In Explorer, open the folder where the mason.exe file you downloaded is located (typically in Downloads)
  3. Still in Explorer, press Ctrl + L, then type cmd and press enter
  4. In the Command Prompt window that opened, type mason.exe -V to ensure the version you downloaded matches what you see:
    $ mason.exe -V
    Mason CLI vX.X # Where X.X is the version you downloaded
    

Linux/macOS

  1. Open a terminal and download the CLI
    1. Linux: run curl -LO $(curl -s https://api.github.com/repos/MasonAmerica/mason-cli/releases/latest | grep "browser_download_url.*linux\"" | cut -d '"' -f 4)
    2. macOS: run curl -LO $(curl -s https://api.github.com/repos/MasonAmerica/mason-cli/releases/latest | grep "browser_download_url.*macos\"" | cut -d '"' -f 4)
    3. macOS Catalina: run curl -LO $(curl -s https://api.github.com/repos/MasonAmerica/mason-cli/releases/latest | grep "browser_download_url.*mason-macos.tar.gz\"" | cut -d '"' -f 4)
  2. Add the CLI to your bin directory
    1. Linux: run mkdir -p ~/.local/bin && mv mason-linux $_/mason && chmod +x $_
    2. macOS: run sudo mkdir -p /usr/local/bin && sudo mv mason-macos $_/mason && chmod +x $_
    3. macOS Catalina: run sudo mkdir -p /usr/local/bin /usr/local/opt && sudo tar xzf mason-macos.tar.gz -C /usr/local/opt/ && sudo ln -sf /usr/local/opt/mason/mason /usr/local/bin/mason
  3. Run mason -V to ensure the version you downloaded matches what you see:
    $ mason -V
    Mason CLI vX.X # Where X.X is the version you downloaded
    
  4. Optional: run echo -e 'eval "$(_MASON_COMPLETE=source mason)"\n' >> .bashrc to get autocomplete support for mason commands in bash.

Mason Platform lifecycle

The Mason CLI provides plumbing to orchestrate changes across your device fleet, but such changes have a lifecycle that must be followed. These steps will give you a general idea of the Mason Platform’s lifecycle:

  1. mason login: Authenticates you with the Mason Platform.
  2. mason register apk: Uploads your app to be used in OS configurations.
  3. Optional: mason register media: Uploads media such as a boot animation to be used in OS configurations.
  4. mason register config: Uploads and builds an OS configuration to be deployed to device groups.
  5. mason deploy config: Deploys an OS configuration to device groups.

Tip: to make this lifecycle easier to manage, we recommend using the mason register project command.

General tips

  • If you are unfamiliar with the terminal, we recommend getting some practice.
  • Use the --help option on any command to get a detailed explanation of how to use it. For example:
    $ mason login --help
    Usage: mason login [OPTIONS]
    ...
    
  • If something goes wrong, rerun the command with -v debug (e.g. mason -v debug login) to get more information. If you think you’ve found a bug, please report it on our issue tracker.

mason help

The help command displays information about any Mason command. Simply run mason help [COMMAND].

mason login

The login command authenticates you with the Mason Platform.

Currently, your session will be saved for ~1 day. If you’d like to end your session earlier than that, run mason logout.

mason logout

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

mason init

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

mason register

The register command lets you upload artifacts to be deployed later to the Mason Platform. To deploy artifacts, see the mason deploy command.

Lifecycle managed registration commands:

Raw artifact registration commands:

Note: Registered artifacts are available here.

mason register project

The register project command lets you upload all artifacts and configurations necessary to deploy a fully functional Mason Project. To register a project, you’ll need to first run mason init or manually configure a .masonrc file. The RC file tells the CLI where to find your OS configurations, APKs, and media.

One of the benefits of using the register project command is its consistency guarantees. When you write your OS config, you can leave out the app and media version codes which tells the CLI to inject the versions of the artifacts that were just uploaded. Here is a minimal OS config with injected versions:

os:
  name: project-id
  version: latest # The "latest" keyword means the CLI will auto-increment versions as necessary
apps:
  - name: Example App
    package_name: com.example.app
media:
  bootanimation:
    name: anim-name

.masonrc schema

The RC file is written in JSON and can be 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"
  }
}

mason register apk

The register apk command lets you upload APKs to be used later in OS configurations or deployed directly to devices.

APK Requirements

Before you register an APK, you must ensure that:

  • It is signed with a non-debug signing key.
  • If it is already deployed,
    • the APK is signed with the same signing certificate you used previously.
    • the versionCode is larger than the previous value.

mason register media

The register media command lets you upload media artifacts to be used later in OS configurations.

Available media types to register are:

Tip: if you don’t need your media to be a specific version, you can use the “latest” keyword in place of the version number.

mason register media bootanimation

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

mason register config

The regiser config command lets you upload OS configurations. These are the core of the Mason Platform, representing a Mason Project to define a device’s behavior. Configs are built and can then be subsequently deployed to a group of devices.

Note: Mason Projects can be found here, device groups here, and build statuses here.

mason deploy

The deploy command lets you make changes to your devices in the field.

Available deployables are:

Note: Once something is deployed, the next successful check-in from a device against the Mason Platform will result in the artifact being retrieved and installed. Since this could could take a non-deterministic amount of time, the --push option is provided to deploy something immediately.

Tip: If you would like to deploy the highest version code available, use the “latest” keyword in place of the version number.

mason deploy apk

The deploy apk command lets you deploy an APK directly without going through the lifecycle of deploying an OS configuration. You’ll need an APK, its version, and a device group to deploy to.

mason deploy config

The deploy config command lets you deploy an OS configuration. This will require a full device reboot and will update the device’s behavior according to the specified configuration. You’ll need a Mason Project, its version, and a device group to deploy to.

mason deploy ota

The deploy ota command lets you update Android’s core components. You will receive emails from us when a new version of Mason OS is available.

mason xray

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

X-Ray Requirements

Before you start using X-Ray, ensure you have the following:

  • Mason CLI v1.5+
  • A device running Mason OS 2.9.0+
  • An API Key with the FLEET:ADMIN scope
  • The target device’s ID

mason xray logcat

The xray logcat command streams logs from the device. Learn more about available logcat arguments here: https://d.android.com/studio/command-line/logcat.

Examples

View logs from a device:

$ mason xray $DEVICE_ID logcat

mason xray pull

The xray pull command copies files from the device. 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.

Examples

Copy the remote file /sdcard/Download/foo.txt into your current directory:

$ mason xray $DEVICE_ID pull Download/foo.txt

mason xray push

The xray push command copies files to the device. 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.

Examples

Copy the local file foo.txt from your current directory to the remote file /sdcard/Download/foo.txt:

$ mason xray $DEVICE_ID push foo.txt Download/

mason xray install

The xray install command installs an APK on a device.

Examples

Install an APK:

$ mason xray $DEVICE_ID install test.apk

mason xray uninstall

The xray uninstall command uninstalls an APK on a device.

Examples

Uninstall an APK:

$ mason xray $DEVICE_ID uninstall com.test.app

mason xray adbproxy

The xray adbproxy command provides support for generic adb commands. Once the xray adbproxy command succeeds, you can run adb connect localhost:$PORT to then execute any adb commands.

Examples

Send adb commands to a device through port 5555:

$ mason xray $DEVICE_ID adbproxy -p 5555
...
$ adb connect localhost:5555
$ adb logcat
...

mason bugreport

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

Examples

Collect a bug report from the device:

$ mason xray $DEVICE_ID bugreport

mason xray screencap

The mason screencap command captures a screenshot from the device.

Examples

Capture a screenshot from the device:

$ mason xray $DEVICE_ID screencap

Capture a screenshot from the device and save the file as test.png:

$ mason xray $DEVICE_ID screencap -o test.png

X-Ray FAQs

How do I disable X-Ray?

By default, the X-Ray feature is enabled once you upgrade your devices to Mason OS 2.9.0+. To disable the X-Ray feature, deploy a project with config_xray_enabled: false to the device:

os:
  name: test
  version: latest
  configurations:
    mason-core:
      config_xray_enabled: false

How do I get an API Key with FLEET:ADMIN scope?

Follow the instructions here: https://docs.bymason.com/mason-api/#api-keys

How do I set my API key?

The following options are available in order of precedence:

  1. Supply your API key on every command execution
    $ mason --api-key $API_KEY ...
    
  2. Supply your API key through an environment variable
    $ export MASON_API_KEY=$API_KEY
    
  3. Set your API key once and persist it across CLI sessions
    $ mason login --api-key $API_KEY
    

Where can I find the device ID?

Log in to your Mason Controller account and click the target device’s serial. Under the Info tab you’ll find the Device ID value.

X-Ray error responses

Error Message Solution
No response from the device,
it may not be connected to the network.
Connect your device to a WiFi or cellular network. Also check the device’s ONLINE/OFFLINE status in the Mason Controller device info page. X-Ray requires the device to be ONLINE in order to function. If the device is OFFLINE, try rebooting the device.
The requested device was not
found.
Ensure your Device ID matches what is reported in Mason Controller.
Access to the requested device
is denied.
Ensure your API Key has the FLEET:ADMIN scope, your device is running Mason OS 2.9.0+, and your project configuration does not have config_xray_enabled: false.
Connection was not accepted on
the device within 30 seconds.
The device user must accept the debugging prompt within 30 seconds.