Mason CLI
The intention of the Mason CLI (Command Line Interface) tool is to provide a common configuration to deploy device ecosystems — from physical hardware and operating systems to apps and network access. Once deployed, Mason CLI can be used to safely and efficiently change the ecosystem as the configuration is evolved. Today pilot customers can use Mason CLI to start deploying applications to their devices in the field.
Installing the CLI
In order to use Mason CLI, you will need Python to be setup correctly on your system. Mason CLI has been currently tested on Python 2.7.x. Please visit the prerequisites page to ensure you have everything needed to correctly install the CLI, as well as instructions on installing the CLI itself.
In summary, the Mason CLI can be installed using the pip tool as follows:
pip install git+https://git@github.com/MasonAmerica/mason-cli.git
To verify installation, you can type mason
to see the following output:
Usage: mason [OPTIONS] COMMAND [ARGS]...
mason-cli provides command line interfaces that allow you to register,
query, build, and deploy your configurations and packages to your devices
in the field.
Options:
-d, --debug
-v, --verbose show verbose artifact and command details
--access-token TEXT optional access token if already available
--id-token TEXT optional id token if already available
--no-color turn off colorized output
--help Show this message and exit.
Commands:
build Build a registered project.
deploy Deploy artifacts to groups.
login Authenticate via user/password.
logout Log out of current session.
register Register artifacts to the mason platform.
stage Stage a project.
version Display mason-cli version.
Mason Platform CLI Usage
In order to use Mason CLI to manage your device configurations, you will need credentials to authenticate against the Mason Platform. Please contact Mason Support to ensure that you have a Mason account configured already. You will need a username and a password to proceed.
Type mason --help
for details on available commands. The various individual commands are described below.
Debugging tip
If you encounter errors that you’re unsure of the reason(s) for, you may want to try the --debug
flag for additional information that might help you diagnose the issue, like so:
mason --debug [command]
Authentication
mason login
provides a means to authenticate against the Mason Platform via username and password. This only needs to be run once; the tool will securely cache the credentials locally to ensure you can re-run the tool without having to reauthenticate each time.
Usage: mason login [OPTIONS]
Authenticate via user/password.
Options:
--user TEXT pass in user
--password TEXT pass in password
--help Show this message and exit.
Enter your username and password to ensure your credentials are saved for future runs:
$ mason login
User: user@example.tld
Password: *********
User authenticated.
Registering Artifacts
mason register
provides a means to register artifacts to the Mason Platform, so that they can be deployed to your devices in the field. Currently the tool supports registering Android packages (APKs) that have already been configured during the pilot/development phase, media files, as well as new project configuration files. The purpose of this command is to register a newer version of an artifact to replace an existing one of an older version.
Usage: mason register [OPTIONS] COMMAND [ARGS]...
Register artifacts to the mason platform.
Options:
-s, --skip-verify skip verification of artifact details
--help Show this message and exit.
Commands:
apk Register apk artifacts.
config Register config artifacts.
media Register media artifacts.
Notes For Artifact Registration
A register operation will NOT cause the artifact to immediately go live – to make the artifact go “live” you’ll need to deploy the artifact to an already defined group of devices (see deploy
). Once that an artifact is deployed, the next successful check-in from a device against the Mason Platform will result in the artifact being retrieved and installed.
Registering APK Artifacts
mason register apk
provides an interface to register android applications (android packages) to the Mason Platform.
Usage: mason register apk [OPTIONS] [APKS]...
Register apk artifacts.
APK - One or many apk's to be registered to the mason platform.
ex:
mason register apk test.apk
multiple in a directory:
mason register apk apks/*.apk
Options:
--help Show this message and exit.
Notes for APK Registration
Before you register an APK, you must ensure that:
It is signed with a non-debug signing key
If already deployed, it is signed with the same signing certificate as the original application that was preinstalled on all devices
The
versionCode
is larger than the previous value. It is recommended that you also change theversionName
for debugging purposes
Registering Config Artifacts
mason register config
provides an interface to register project definitions (in YAML) to the Mason Platform. Once a configuration file is registered, it can be utilized in build
to generate a new mason package, and then deploy
to be released to a group of devices.
Usage: mason register config [OPTIONS] YAML
Register config artifacts.
YAML - The yaml file describing the configuration.
ex:
mason register config test.yml
Options:
--help Show this message and exit.
Notes for Config Registration
Before you register a configuration, you must ensure that:
The project (os name) has been created in the Mason Platform Dashboard
A device type has been chosen from the project creation drop down
For more notes on the YAML format and the project definition in a configuration file, see Mason Project definition.
Registering Media Artifacts
mason register media
provides an interface to register certain media artifacts to be included for customization for a Mason Project. Currently, the only media configuration supported is that of a bootanimation
. For more information on bootanimations, see Boot Animation definition.
Usage: mason register media [OPTIONS] BINARY NAME TYPE VERSION
Register media artifacts.
NAME - The name of the media artifact.
TYPE - The given type of the media artifact.
supported:
- bootanimation
VERSION - The version of the media artifact.
ex:
mason register media bootanimation.zip my-boot-anim-1 bootanimation 1
Building a Configuration
mason build
provides an interface for building a project that is defined in YAML and registered to the Mason Platform.
Once you’ve defined and registered a configuration file for a project (see mason register config
), you’ll be able to build the configuration into an OTA(Over-The-Air) package that can be deployed to a group of devices.
Once you invoke a build, you can see the build status in the Mason Build Dashboard.
Usage: mason build [OPTIONS] PROJECT VERSION
Build a registered project.
PROJECT - The name of the configuration project
VERSION - The version of the configuration project
The name and the version of the configuration project can be found in the
YAML definition which was registered to the mason platform.
As an example, a registered yaml:
os:
name: mason-test
version: 5
becomes a build command:
mason build mason-test 5
Options:
--help Show this message and exit.
For more notes on the YAML format and the project definition in a configuration file, see Mason Project definition.
Deploying Artifacts
mason deploy
provides an interface to deploy a configuration or application to a group of devices in the field.
Usage: mason deploy [OPTIONS] COMMAND [ARGS]...
Deploy artifacts to groups.
Options:
-s, --skip-verify skip verification of deployment
-p, --push push the deployment to devices in the field
--help Show this message and exit.
Commands:
apk Deploy apk artifacts.
config Deploy config artifacts.
For more notes on groups, see Mason Group definition. For more notes on the YAML format and the project definition in a configuration file, see Mason Project definition.
Deploying APK Artifacts
Once you’ve registered an APK (see mason register apk
), you’ll be able to deploy the application (by version code) to a group of devices.
Usage: mason deploy apk [OPTIONS] NAME VERSION GROUP
Deploy apk artifacts.
NAME - The package name of the apk to be deployed
VERSION - The versionCode of the apk
GROUP - The target group to deploy to
As an example, a registered apk:
package_name: com.test.app
version_code: 3
to deploy to group `development` becomes:
mason deploy com.test.app 3 development
this can be used in conjunction with the --push argument
Options:
--help Show this message and exit.
For more notes on groups, see Mason Group definition.
Deploying Config Artifacts
For a configuration deploy, you’ll need to define and register a configuration file for a project (see mason register config
), and have invoked a successful build for that project:version combo. (see mason build
).
Usage: mason deploy config [OPTIONS] NAME VERSION GROUP
Deploy config artifacts.
NAME - The name of the configuration to be deployed
VERSION - The version of the configuration to be deployed
GROUP - The target group to deploy to
As an example, a registered yaml:
os:
name: mason-test
version: 5
to deploy to group `development` becomes:
mason deploy mason-test 5 development
this can be used in conjunction with the --push argument
Options:
--help Show this message and exit.
For more notes on the YAML format and the project definition in a configuration file, see Mason Project definition.
Helper Functions of mason-cli
“Stage” command
mason stage
provides an interface to quickly register and build a project that is defined in YAML format.
Instead of separately running mason register config
and mason register build
, you can shortcut the roundtrip via
mason stage
Usage: mason stage [OPTIONS] YAML
Stage a project.
YAML - The configuration file to register and build.
The stage commands allows you to register a configuration file and
immediately start a build for it.
Options:
-s, --skip-verify skip verification of config stage
--help Show this message and exit.