Mason CLI

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

Installing the CLI

Visit the latest release of the Mason CLI's GitHub page. Under the “Assets” section, download the variant of the CLI for your platform.


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


  1. Open a terminal in the directory the CLI was downloaded
  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. Run mason -V to ensure the version you downloaded matches what you see:
$ mason -V
  1. Optional: run echo -e 'eval "$(_MASON_COMPLETE=source mason)"\n' >> .bashrc to get autocomplete support for mason commands in bash.

macOS Catalina

If you run into security exceptions on macOS Catalina, check here for workarounds.

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 stage: Uploads and builds an OS configuration to be deployed to device groups.
  5. mason deploy config: Deploys an OS configuration to device groups.

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 to get more information. If you think you've found a bug, please report it on our issue tracker.

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 register

The register command lets you upload artifacts to be used later in OS configurations. To deploy artifacts, see the mason deploy command.

Available artifact types to register are:

Note: Registered artifacts are available here.

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:

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 can be built and then subsequently deployed to a group of devices.

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

mason stage

The stage command registers a config and then immediately builds it. These two steps must be performed before an OS configuration can be deployed to devices, so this command is the recommended way to register a config.

After building an OS configuration, you'll probably want to deploy it.

To view the status of your builds, check here.

mason build

The build command lets you build a previously registered OS configuration.

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.

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.