Using Persistent Mobile Foundation CLI to Manage Artifacts

Overview

Persistent Mobile Foundation provides a Command Line Interface (CLI) tool for the developer, pmfdev, to easily manage client and server artifacts.
Using the CLI you can manage Cordova-based applications that uses the PMF Cordova plug-in, and Native applications that uses the PMF Native SDK.

You can also create, register, and manage adapters to either local or remote PMF instances, and administer projects from the command line or via REST services, or from the PMF Operations Console.

The pmfdev commands have two modes: interactive mode and direct mode. In interactive mode, you enter the command without options, and you are prompted for responses. In direct mode, you enter the full command, including options, and prompts are not provided. When applicable, the prompts are context-sensitive to the target platform of the app, as determined by the directory from which you run the command. Use the up and down arrow keys on your keyboard to move through the selections, and press the Enter key when the selection you want is highlighted and preceded by a “>” character.

In this tutorial you will learn how to install the pmfdev Command Line Interface (CLI) and how to use it to manage PMF instances, applications and adapters.

For more information regarding SDK integration in Cordova and Native applications, see the tutorials in the Adding the PMF SDK category.

Jump to

• Prerequisites
• Installing the PMF CLI
• List of CLI commands
• Interactive and Direct modes
• Managing PMF instances
• Managing Applications
• Managing and Testing Adapters
• Helpful commands
• Update and Uninstall the Command Line Interface

Prerequisites

The PMF CLI is available as an NPM package at the NPM registry.

Ensure node.js and npm is installed in the development environment in order to install NPM packages.
Follow the installation instructions in nodejs.org to install node.js.

To confirm that node.js is properly installed, run the command node -v.

node -v
v8.11.1

Note: Minimum supported node.js version is 8.x. Also, with the fast evolving node and npm packages, the PMF CLI might not be fully functional with all the available versions of node and npm including the latest versions.

Installing the PMF CLI

To install the Command Line Interface run the command:

npm install -g pmfdev-cli --no-optional

If the CLI .zip file was downloaded from the Download Center of the PMF Operations Console, use the command:

npm i -g <file location.tgz>

• To install the CLI without optional dependencies add the --no-optional flag: npm install -g --no-optional path-to-pmfdev-cli.tgz

To confirm the installation, run the command pmfdev without any arguments and it will print the help text:

NAME
     Persistent Mobile Foundation Command Line Interface (CLI).

SYNOPSIS
     pmfdev <command> [options]

DESCRIPTION
     The Persistent Mobile Foundation Command Line Interface (CLI) is a command-line
     for developing PMF applications. The command-line can be used by itself, or in conjunction
     with the Persistent Mobile Foundation Operations Console. Some functions are available from  
     the command-line only and not the console.

    ...
    ...
    ...

List of CLI commands

Interactive and Direct modes

All commands can be executed in interactive or direct mode. In the interactive mode, the parameters required for the command will be prompted and some default values will be used. In direct mode, the parameters must be provided with the command being executed.

Example:

pmfdev server add in interactive mode:

? Enter the name of the new server definition: mydevserver
? Enter the fully qualified URL of this server: http://mydevserver.example.com:9080
? Enter the PMF administrator login ID: admin
? Enter the PMF administrator password: *****
? Save the admin password for this server?: Yes
? Enter the context root of the Persistent Mobile Foundation administration services: mfpadmin
? Enter the PMF connection timeout in seconds: 30
Verifying server configuration...
The following runtimes are currently installed on this server: mfp
Server profile 'mydevserver' added successfully.

The same command in direct mode would be

pmfdev server add mydevserver --url http://mydevserver.example.com:9080 --login admin --password admin --setdefault

To find what is the right syntax for a command in direct mode use pmfdev help <command>.

Managing PMF instances

You can use pmfdev server <option> command to manage the instances of PMF that are in use. There must be always at least one server instance listed as the default instance. The default server is always used if another one was not specified.

List server instances

To list all the PMF instances available to be used, run the command:

pmfdev server info

By default, a local server profile is created automatically and used as the current default by the CLI.

Add a new server instance

If you are using another local or remote PMF instance you can add it to the list of instances available to be used with the command:

pmfdev server add

Follow the interactive prompt to provide a name to the server, the server URL and user/password credentials.
For example, to add a PMF that is running on cloud you would do the following:

$ pmfdev server add
? Enter the name of the new server profile: MyBluemixServer
? Enter the fully qualified URL of this server: https://mobilefoundation-7abcd-server.mybluemix.net:443
? Enter the PMF administrator login ID: admin
? Enter the PMF administrator password: *****
? Save the administrator password for this server?: Yes
? Enter the context root of the Persistent Mobile Foundation administration services: mfpadmin
? Enter the PMF connection timeout in seconds: 30
? Make this server the default?: Yes
Verifying server configuration...
The following runtimes are currently installed on this server: mfp
Server profile 'MyBluemixServer' added successfully.

• Replace the “fully qualified URL of this server” with your own.

Edit server instances

If you want to edit the details of a registered server instance, run the following command and follow the interactive prompt to select the server to be edited and provide the information to be updated.

pmfdev server edit

To set a server as the default one, use:

pmfdev server edit <server_name> --setdefault

Remove server instances

To remove a server instance from the list of registered servers, run the command:

pmfdev server remove

And select the server from the interactive list

Start and stop local server

To start a local server, run the command:

pmfdev pmfservices start

It runs the following tasks:

• Pulls the Persistent Mobile Foundation CE Image from Docker hub
• Starts the Persistent Mobile Foundation services locally as docker container
• If this command is run from a directory where mfpconfig folder is present then it uses the application details provided in app_config.json and registers it with the just started server.
• If this command is run from any other directory or subdirectory of the app that does not contain the mfpconfig folder then it just follows register command Note: To know more about the mfpconfig folder refer to the {: #create-a-starter-application } command

To stop a local server, run the command:

pmfdev pmfservices stop

This command stops the Persistent Mobile Foundation services.

Open PMF Operations Console

To open the console of the default server registered run the command:

pmfdev server console

To open the console of another server, inform the server name as a parameter of the command:

pmfdev server console <server_name>

Remove apps and adapters from a server

To remove all apps and adapters registered in a server run the command:

pmfdev server clean

And select the server to clean form the interactive prompt.
This will put the server instance in a clean state without any app or adapter deployed.

Managing applications

The command pmfdev app <option> can be used to manage applications created with the PMF SDK.

Create a starter application

To create an app, run the following command

pmfdev app create

This command creates a starter app in the current working directory. It takes the app details as input from the following.

• Interactive prompts

• Command line options

  pmfdev app create -t native -i com.test -av 1.0.0 -p android -s push
  

• Configuration JSON files that is Application Configuration and Server Configuration

  pmfdev app create -ac <path to app configuration json> -sc <path to server configuration json>
  

Along with the application folders, it creates a configuration folder mfpconfig with two files under it.

• app_config.json - this file has the application related confguration
• server_config.json - this file has the server related details

These files (if exists) are used by pmfdev app register and pmfdev pmfservices start commands to register the application with the server.

Note: If you have an application that was not created by the instructions in this section, but you want to add the mfpconfig folder to it then the work around is to create a starter app providing the Application Configuration and Server Configuration as inputs and then copying over the generated mfpconfig folder and its contents to the root folder of your existing app.

Register an application in a server instance

An application must be registered in a PMF when it is ready to be executed.
To register an app, run the following command from the root folder of the app project:

pmfdev app register

This command can be executed from the root of a Cordova, Android, iOS or Windows application.
It will use the default server and runtime to run the following tasks:

• Register an application with a server.
• Generate a default client properties file for the application.
• Put the server information into the client properties file.

For a Cordova application, this command will update the config.xml file.
For an iOS application, this command will update the mfpclient.plist file.
For an Android or Windows application, this command will update the mfpclient.properties file.

To register an app to a server and runtime that is not the default one, use the syntax:

pmfdev app register <server> <runtime>

For Cordova Windows platform, the -w <platform> argument must be added to the command. The <platform> argument is a comma separated list of the windows platforms to be registered. Valid values are windows,windows8 and windowsphone8.

pmfdev app register -w windows8

If this command is run from a directory or from an application where mfpconfig folder is present, then it uses the application details provided in the app_config.json and registers it with the server provided in the server_config.json. If server_config.json is not present, then it registers it with the default server. Note: To know more about the mfpconfig folder refer to the {: #create-a-starter-application } command

Configure an application

When an application is registered, server related attributes are added to its configuration file.
To change the values of these attributes, run the following command:

pmfdev app config

This command will interactively present a list of attributes that can be changed, and prompt for the new value of the attribute.
The attributes available will vary for each platform (iOS, Android, Windows).

Available configurations are:

• The server address and runtime the application will be registered to

  Example use case: in order to register an application to a PMF with a certain address, but also have the application connect to a different server address, for example a DataPower appliance:

  1. Run pmfdev app register to register the application in the expected PMF address.
  2. Run pmfdev app config and change the server property’s value to match the address of the DataPower appliance. You can also run the command in direct mode: pmfdev app config server http(s)://server-ip-or-host:port.

• Setting a public key for the Direct Update authenticity feature
• Setting application default language (default is English (en))
• Whether or not to enable the web resources checksum test
• What file extensions to ignore during the web resources checksum test

Preview a Cordova application

A Cordova application’s web resources can be previewed using a browser. Previewing an application allows for fast and rapid develop without needing to use native platform specific emulators and simulators.

Before running the preview command, you must prepare the project by adding the wlInitOptions variable. Complete the following steps:

1. Add the wlInitOptions variable to your main JavaScript file, which is index.js in a standard Cordova app.

   var wlInitOptions = {
      mfpContextRoot:'/mfp', // "mfp" is the default context root of PMF
      applicationId:'com.sample.app' // Replace with your own value.
   };
   

2. Register the app again by using the following command:

   pmfdev app register
   

3. Run the following command:

   cordova prepare
   

4. Preview the Cordova application by running the following command from the Cordova application root folder:

   pmfdev app preview
   

You will be prompted to select which platform to preview and which type of preview to use. There are two options of preview: MBS and Browser.

• MBS - Mobile Browser Simulator. This method simulates a mobile device in a browser, as well as provide rudimentary Cordova API simulation such as Camera, File Upload, Geolocation and more. Note: You cannot use the cordova-browser with the MBS option.
• Browser - Simple Browser Rendering. This method presents the www resources of the Cordova application as a usual browser web page.

For more details about the preview options see the Cordova development tutorial.

Update web resources for Direct Update

The web resources of a cordova app, like .html, .css and .js files inside www folder can be updated without the need to reinstall the app at the mobile device. This is possible with the Direct Update feature provided by PMF.

For more details about how Direct Update works see the tutorial Using Direct Update in Cordova applications.

When you want to send a new set of web resources to be updated in a cordova application, run the command

pmfdev app webupdate

This command will package the updated web resources to a .zip file and upload it to the default PMF registered. The packaged web resources can be found at the [cordova-project-root-folder]/mobilefirst/ folder.

To upload the web resources to different server instance, inform the server name and runtime as part of the command

pmfdev app webupdate <server_name> <runtime>

You can use the –build parameter to generate the .zip file with the packaged web resources without uploading it to a server.

pmfdev app webupdate --build

To upload a package that was previously built, use the –file parameter

pmfdev app webupdate --file mobilefirst/com.ibm.test-android-1.0.0.zip

Additionally the resources can be encrypted by using the command

pmfdev app webencrypt

This command specifies that an encrypted version of the contents of the platform’s wwww directory be created for deploying to mobile devices. Available for iOS and Android platforms only.

Pull and Push the PMF Application configuration

After a PMF Application is registered in a PMF, it is possible to change some of the application configurations using the PMF Console and them pull those configurations from the server to the application with the following command:

pmfdev app pull

It is also possible to change the application configurations locally and push the changes to the PMF with the command:

pmfdev app push

Example: scope mapping to security checks can be performed in the PMF Operations Console, and then be pulled from the server using the abve command. The downloaded .zip file is stored in the project’s [root directory]/mobilefirst folder, and can be later used with the pmfdev app push to upload it to a different PMF, allowing for fast configuration and setup by re-using the predefined configuration.

Managing and Testing Adapters

It is possible to manage adapters with the command pmfdev adapter <option>.

To learn more about adapters see the tutorials at the Adapters category.

Create an Adapter

To create a new Adapter, use the command

pmfdev adapter create

And follow the prompt to inform the name, type and group id of the adapter

Build an Adapter

To build an adapter, run the following command from the adapter’s root folder:

pmfdev adapter build

This will generate a .adapter file at the **/target** folder.

Deploy an Adapter

The following command will deploy the adapter to the default server:

pmfdev adapter deploy

To deploy to a different server, use:

pmfdev adapter deploy <server_name>

Call an Adapter from the command line

After an adapter is deployed it is possible to call the adapter from the command line to test it’s behavior with the command:

pmfdev adapter call

You will be prompted to inform the adapter, procedure and parameters to use. The output of the command will be the response of the adapter procedure.

Learn more in the Testing and debugging adapters tutorial.

Helpful commands

To set preferences of the pmfdev CLI, such as default browser and default preview mode, use the command:

pmfdev config

To see the help content describing all pmfdev commands, use:

pmfdev help

The following command will generate a list with information about your environment:

pmfdev info

To print the version of the pmfdev CLI, use:

pmfdev -v

Update and Uninstall the Command Line Interface

To update the command line interface run the command:

npm update -g pmfdev-cli

To uninstall the command line interface run the command:

npm uninstall -g pmfdev-cli