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 usingmason 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?
- Visit our FAQ
- Contact us at support@bymason.com
- Report bugs or add feature requests using our issue tracker.