Command-Line Interface (CLI) of webOS Open Source Edition (OSE). It provides a collection of commands used for creating, packaging, installing, and launching apps or services in the command line environment. CLI lets you develop and test apps or services without using any IDE.
Key Features
CLI provides the following key features:
App and Service Creation
Provides standard templates for webOS OSE apps and services
Provides a list of available templates
Generates an app or a service and configures basic information
App and Service Packaging
Packages the source code and generates a package file (.ipk) to run on the target device
Provides a feature to exclude sample and test code directories from an app or a service
Target Device Management
Provides a list of target devices
Adds, modifies, and removes target devices
App and Service Installation
Installs the app and service on the target device
Provides a list of apps installed on the target device
Removes selected apps from the target device
App Launching and Closing
Launches selected apps
Closes apps that are running
Provides the list of apps running on the target device
App and Service Debugging
Enables Web Inspector for debugging web apps
Enables Node’s Inspector for debugging JavaScript services
Provides web app information
Provides JavaScript service information
System Requirements
Operating Systems
Required version for each operating system are as follows:
OS
Requirement
Linux
Ubuntu 18.04 LTS 64-bit
macOS
Mac OS X 10.13 High Sierra or higher
Windows
Windows 10 64-bit
Software Tools
Node.js (Use v8.12.0 to v14.15.1.)
npm
Installing CLI
You can install CLI using the following command. It is recommended to install CLI globally.
For Linux and macOS, sudo command might be required depending on the environment.
After the installation, check if the installed version matches with the latest version of CLI npm package.
CLI Workflow
webOS OSE CLI provides features for developing web apps throughout the whole development process. The figure below shows some of CLI commands that can be used during each stage of the development process.
This command creates a webOS app or service from a template. ares-generate displays a list of available templates for a web app, JS services, and webOS configuration files.
Specifies a directory where the package file is created.
-c, --check
None
Checks whether the application's appinfo.json file exists or not. This option does not make package file. If appinfo.json file does not exist, warning messages appear.
-e, --app-exclude
EX_DIR
Lists the directories to exclude in the package file.
-r, --rom
None
Proceeds up to the stage just before creating package file phase.
-h, --help
None
Displays the help of the ares-package command.
-V, --version
None
Displays the version of the CLI.
-v
None
Displays the execution log.
Parameters
Parameter
Description
APP_DIR
Specifies the directory where the application's appinfo.json file is located.
SERVICE_DIR
Specifies the directory where the service's services.json file is located.
OUT_DIR
Specifies the directory where the package file is to be created. If the directory is not entered, the package file is created in the same directory as the command.
EX_DIR
Specifies the name of directories and files to exclude from the application when packaging the package file. You should enter directories used for samples and tests. All subdirectories and files in the specified directory are excluded. And specified files also are excluded.
To exclude multiple directories, enter as -e subdir -e filename. You can use common pattern expression such as wildcard (*).
Examples
Here are some examples of the different uses:
Creating a package file from ./sampleApp directory and outputting it in the working directory
ares-package sampleApp
Creating a package file from the ./sampleApp directory and outputting it in ./output directory
ares-package -o output sampleApp
Creating a package file except for testCode1 sub-directory, README.md file and all text file (.txt)
Creating a package file with an external JS service (using absolute path)
# Windows
ares-package c:\samples\sampleApp c:\samples\sampleService
#Linux/MacOS
ares-package ~/samples/sampleApp ~/samples/sampleService
ares-setup-device
This command displays a list of registered target devices. You can add, modify, or remove them from the list. This command is mainly used to modify target’s host address which is running on a remote host. If you execute the command without any options, the command runs in interactive mode.
Adds a target device with the specified information.
-m, --modify
TARGET_NAME
Modifies a target device's information. You can change the information of the target device except for its name.
-i, --info
DEVICE_INFO
Sets information for the target device.
-r, --remove
TARGET_NAME
Deletes a target device that matches the device name you enter.
-f, --default
TARGET_NAME
Sets a default target device.
If you don't set a target device, the default target device is used as the target device.
-R, --reset
None
Initializes the list of registered target devices.
-l, --list
None
Lists registered target devices.
-F, --listfull
None
Lists registered target devices' information with more detail (JSON string).
-h, --help
None
Displays the help of the ares-setup-device command.
-V, --version
None
Displays the version of the CLI.
-v
None
Displays the execution log.
Parameters
Parameter
Description
DEVICE_INFO
Specifies the information of the target device. It can be entered using strings in the format of "key=value" or JSON-type such as "{'key1':'value1', 'key2':'value2', ...}". You can use the following items as key for the target device:
name: Target device name
description: Target device description
host: Target device host address
port: Target device port number
username: Username for accessing the target device. Possible values:
root (default) – To be used by internal users only.
password: Password for authenticating the root user.
By default the password for root user is blank.
If the password was previously set for a root user, then enter it here.
privatekey: Filename of SSH private key.
Not applicable to the root user.
For the device, do not enter anything, leave it blank. The value will be auto-generated by using the passphrase provided by the user.
passphrase: Passphrase for using the SSH private key file.
default: Setting a default device.
Enter true to set a default device. Default value is false.
This key must be used with --add option.
When using CLI in interactive mode, take care when entering the required values or choosing to use the default values, otherwise you might not be able to use the device.
TARGET_NAME
Specifies the name of the target device.
The following example shows a DEVICE_INFO written in JSON format:
"{'host':'127.0.0.1', 'port':'22'}"
Examples
Here are some examples of the different uses:
Listing target devices
ares-setup-device --list
name deviceinfo connection profile
------------------ ------------------------ ----------- -------
emulator (default) developer@127.0.0.1:6622 ssh ose
Adding the target device with interactive mode (target device name: target, host address: 10.123.45.67, port number: 22, user: root)
ares-setup-device
name deviceinfo connection profile
------------------ ------------------------ ----------- -------
emulator (default) developer@127.0.0.1:6622 ssh ose
** You can modify the device info in the above list, or add a new device.
? Select: add
? Enter Device Name: target
? Enter Device IP address: 10.123.45.67
? Enter Device Port: 22
? Enter ssh user: root
? Enter description: sample
? Select authentication: password
? Enter password: [hidden]
? Set default? Yes
? Save? Yes
name deviceinfo connection profile
------------------ ------------------------ ---------- -------
target (default) root@10.123.45.67:22 ssh ose
emulator developer@127.0.0.1:6622 ssh ose
Note If you want to input default value or set empty, press the enter key without any value.
Modifying the target device (target device name: target, port number: 9922)
ares-setup-device --modify target -i "port=9922"
Modifying the target device with interactive mode (target device name: target, port number: 9922)
ares-setup-device
name deviceinfo connection profile
------------------ ------------------------ ---------- -------
target (default) root@10.123.45.67:22 ssh ose
emulator developer@127.0.0.1:6622 ssh ose
** You can modify the device info in the above list, or add a new device.
? Select: modify
? Enter Device Name: target
? Enter Device IP address: 10.123.45.67
? Enter Device Port: 9922
? Enter ssh user: root
? Enter description: sample
? Select authentication: password
? Enter password: [hidden]
? Save? Yes
name deviceinfo connection profile
---------------- ------------------------ ---------- -------
target (default) root@10.123.45.67:9922 ssh ose
emulator developer@127.0.0.1:6622 ssh ose
Note If you want to keep the previous value, press the enter key without any value.
Setting the default device (target device name: target)
ares-setup-device --default target
Removing the target device (target device name: target)
ares-setup-device --remove target
Note To remove or set a target device, you only need to enter the name of the target device following the command.
ares-install
This command installs the app for a specified app package file (.ipk) on the target device. You can also see the list of apps installed on the target device or remove them with this command.
This command launches or terminates the application installed on the target device. This command can also display the list of applications running on the target device.
Specifies the target device. Unless specified, it will be set to the default target device.
--close
APP_ID
Terminates application on the target device.
-r, --running
None
Lists applications that are running on the target device.
-p, --params
PARAMS
Launches an application with specified parameters.
-dp, --display
DISPLAY_ID
Launches an application on a specified display.
-D, --device-list
None
Lists all the available devices.
-H, --hosted
APP_DIR
Runs an app without installation
-h, --help
None
Displays the help of the ares-launch command.
-V, --version
None
Displays the version of the CLI.
-v
None
Displays the execution log.
Parameters
Parameter
Description
APP_ID
ID of the application to launch or terminate.
APP_DIR
Working directory of an app.
If --hosted option is used with a directory path, an app (ID: com.sdk.ares.hostedapp) is launched on the target device. The launched opens the files in the APP_DIR directory.
To close this app, use --close option with com.sdk.ares.hostedapp as an APP_ID.
DISPLAY_ID
ID of the display to launch an app. It should be an integer type. (Use 0 for primary display and 1 for secondary display.)
TARGET_DEVICE
Specifies the target device on which the application is installed.
PARAMS
Specifies the parameters which are used on application launching. It is entered using JSON-type strings in the format "{'param1':'value1', 'param2':'value2 which contains spaces', ...}".
Examples
Here are some examples of the different uses:
Launching the application installed on the target device
Note When you use a parameter, the web app will receive the parameter with the webOSLaunch event. For more detailed information on the webOSLaunch event, see Web App Lifecycle.
This command enables Web Inspector or Node’s Inspector. Each inspector displays the run-time information of a web application or a JS service, respectively.
Caution
We highly recommend you to use the same version as Chrome/Chromium of webOS OSE. Using other versions might cause unexpected errors.
To check the Chromium version of your target device, do one of the following:
Execute the ares-device -i command. In this case, make sure username of the target device is set as root. Otherwise the Chromium version won’t be displayed. For more details, see DEVICE_INFO of ares-setup-device.
Specifies the target device. Unless specified, it will be set to the default target device.
-a, --app
APP_ID
Specifies the application to debug with Web Inspector.
-s, --service
SERVICE_ID
Specifies the JS service to debug with Node's Inspector.
-o, --open
None
Opens the default browser of the host machine.
Note
This option is only available for Web Inspector, thus can be used with --app|-a option only.
Web Inspector works in the Blink-based web browsers (e.g. Chrome or Opera) only. You have to re-open the inspector page in one of those browsers if another browser is your default web browser (e.g. Safari or Internet Explorer).
To connect to Node's Inspector, you need to use one of the Node's Inspector clients, such as Chrome DevTools and Visual Studio Code. For more information, see Inspector Clients.
-D, --device-list
None
Lists all the available devices.
-dp, --display
DISPLAY_ID
Launches an application and opens Web Inspector on a specified display.
-h, --help
None
Displays the help of the ares-inspect command.
-V, --version
None
Displays the version of the CLI.
-v
None
Displays the execution log.
Parameters
Parameter
Description
APP_ID
ID of the application whose information is to be viewed using the Web Inspector.
SERVICE_ID
ID of the JS Service whose information is to be viewed using the Node's Inspector.
TARGET_DEVICE
Specifies the target device on which the application is installed.
This command runs a web server for testing a local file. The web server will run on the given path. You can terminate the web server by pressing Control+C on the shell prompt.