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 the versionName 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.