Command Line Interface

Version added 07-Mar-2018| Modified 31-Jul-2018

The command-line interface (CLI) provides a collection of commands used for creating, packaging, installing, and launching the web app in the command line environment. The CLI allows you to develop and test app without having to use a specific IDE.

Starting from CLI v1.8.1, you must accept our SDK end-user license agreement (EULA) to use the CLI.
The EULA will appear when you execute any of the CLI commands. Once you accept the EULA for the CLI version, you can proceed with using the CLI. Otherwise, you will be prompted to accept the EULA for each command input.

Download

Installation

Unzipping the Package

Unzip the downloaded CLI package. After unzipping the package, you can execute the CLI commands located in the following directories.

  • Windows: ares-cli

  • Linux & Mac OS: ares-cli/bin

(Windows Only)

Due to recursively nested directory structure of Node.js modules used by CLI, the resulting path length may exceed the maximum path length of Windows. To prevent issues while installing and using CLI, we strongly recommend that you do the following: 

  • To unzip the package, use a program that supports file pathnames longer than 260 characters, such as 7-Zip.

  • Unzip the package under the root directory (for example, C:\ or D:\).

To make it easy to execute CLI commands, you need to add the CLI directory to PATH environment variable.

Set Directory - Windows

If you unzipped the package under C:\, the CLI commands would be located in C:\ares-cli. You need to add the directory to the environment variable. 

You can create a system variable pointing to the directory and add the system variable to the PATH.

C:\> setx /m WEBOS_CLI_HOME "C:\ares-cli"
C:\> setx /m PATH "%WEBOS_CLI_HOME%;%PATH%"

Otherwise, you can add the directory to the PATH directly.

C:\> setx /m PATH "C:\ares-cli; %PATH%"

To set the PATH for current user only, remove "/m" from the commands above.

To make the changes take effect, you must restart the command prompt.

Set Directory - Linux & Mac OS 

There are many ways to set the environment variable in Linux and Mac OS. Here, we describe the method to add the information to the .profile so that the PATH is automatically configured each time the shell is executed. We will assume that the CLI has been unzipped under the home directory.

First, open the .profile which is located in the home directory. If the file does not exist, the command will create one.

$ vi ~/.profile

Add the lines below at the end of the file.

...
# add CLI path
if [ -d "$HOME/ares-cli/bin" ]; then
  export PATH="$PATH:$HOME/ares-cli/bin"
fi

To make the changes take effect, you must execute the following command or restart the shell  .

$ source ~/.profile

Command Usage

With the CLI, you can install your app on the target device. You can also retrieve, run, terminate, and remove the apps that are installed on the platform of webOS Open Source Edition. 

For step-by-step instructions to create web apps and JS service using CLI commands, see Creating Web Apps and Creating JS Services. 

The CLI can be used during any of the following stages of the development process:

Development_Process_with_CLI_-_No_Dev_Mode.png

The following shows the commands you could use:

Commands

Descriptions

ares

Provides the help menu for using the ares commands.

ares-generate

Creates a web app from a template.

ares-package

Creates an app package file.

ares-setup-device

Manages the target devices.

ares-install

Installs an app on the target device.

ares-launch

Runs or terminates the web app.

ares-inspect

Runs the Web Inspector or Node Inspector for debugging web app or JS service.

ares-server

Runs the Web server for testing local app file.

ares-shell

Executes shell commands in the target device.

ares-push

Pushes file(s) from a host machine to a target device.

ares-pull

Pulls file(s) from a target device to a host machine.

Open All


ares-generate

This command creates an app from a template. ares-generate displays a list of available templates for a web app, JS services, and webOS config file (appinfo.json) creation.

Usages

ares-generate [OPTION...] APP_DIR

ares-generate [OPTION...] -t js_service SERVICE_DIR

ares-generate --list|-l

ares-generate --version

ares-generate --help|-h

Options

Option

Parameter

Description

-t, --template

TEMPLATE

Uses the specified template. Available templates are:

Template Name

Brief Description

basic

(default) Basic web app template.

hosted_webapp

Hosted web app template.

webappinfo

Creates a 'appinfo.json' file for web apps.

js_service

JS service template.

jsserviceinfo

Creates a 'services.json' and 'package.json' file for JS services.

webicon

Icon files for web apps [80x80, 130x130].

-p, --property

PROPERTY

Saves the application information that is entered.

-s, --servicename

SERVICE_NAME

Specifies the JS Service ID.

-f, --overwrite

None

Allows overwriting of existing files.

-l, --list

None

Lists the available templates. See description of the -t option above.

-v

None

Displays the execution log.

-V, --version

None

Displays the version of the ares-generate command.

-h, --help

None

Displays the help of the ares-generate command

Parameters

Parameter

Description

APP_DIR

Specifies the app project directory. If the directory does not exist, the directory will be created while executing the command.

SERVICE_DIR

Specifies the service directory. If the specified directory does not exist, the directory will be created while executing the command.

PROPERTY

Specifies the app information. It is entered using JSON-type strings in the format of "Key=Value" or "{'key1':'value1', 'key2':'value2', ...}".

TEMPLATE

Specifies the template to use when creating a project. The default value is basic.

SERVICE_NAME

ID of the service you are creating. The service ID should be a sub-domain of the ID of the app which the service belongs to.

Examples

Here are some examples of the CLI usage:

Listing the templates (web application templates)

ares-generate -l

 

Creating a web application with the default template in ./sampleApp directory

ares-generate sampleApp

 

Creating a web application with custom App ID in ./sampleApp directory

ares-generate -p "id=com.example.sampleapp" sampleApp

 

Creating a JS Service with custom Service ID in ./sampleService directory

ares-generate -t js_service -s com.example.sampleapp.sampleservice sampleService

The service ID should be a sub-domain of the ID of the app which the service belongs to.

 

Creating a web app in the ./sampleApp and setting properties with JSON string

ares-generate -p "{'id':'com.example.sampleapp', 'version':'1.0.0', 'icon':'icon.png', 'type':'web', 'title':'Sample App', 'main':'index.html'}" sampleApp

 


ares-package

This command packages an app and JS service into a package file (.ipk) which is stored in a specified directory.

Usages

ares-package [OPTION...] APP_DIR [SERVICE_DIR]

ares-package --version

ares-package --help|-h

Options

Option

Parameter

Description

-o, --outdir

OUT_DIR

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.

-v

None

Displays the execution log.

-V, --version

None

Displays the version of ares-package command.

-h, --help

None

Displays the help of ares-package command.

Parameters

Parameter

Description

APP_DIR

Specifies the directory of the application to be packaged.

SERVICE_DIR

Specifies the directory where JS service's package.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)

ares-package -e "testCode1" -e "README.md" -e "*.txt" samplePrj

 

Creating a package file with external JS service directory

ares-package sampleApp sampleService


ares-setup-device

This command displays a list of registered target devices. You can also add, modify or remove them from the list. This command is mainly used to modify target host address which is running on a remote host. If you execute the command without any options, the command runs in interactive mode.

Usages

ares-setup-device

ares-setup-device [OPTION...] --add|-a [TARGET_NAME] [--info|-i [DEVICE_INFO]]

ares-setup-device [OPTION...] --modify|-m [TARGET_NAME] [--info|-i [DEVICE_INFO]]

ares-setup-device [OPTION...] --remove|-r [TARGET_NAME]

ares-setup-device --search|-s

ares-setup-device [--search|-s] --timeout|-t [TIMEOUT]

ares-setup-device --reset|-R

ares-setup-device --list|-l

ares-setup-device --listfull|-F

ares-setup-device --version|-V

ares-setup-device --help|-h

Options

Option

Parameter

Description

-a, --add

TARGET_NAME

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.

-s, --search

None

Searches webOS devices in the same network with SSDP and displays the found device list. When you select a device from the device list, IP address of the selected device will be set for device information automatically.

-t, --timeout

TIMEOUT

Sets timeout value for the --search option. This option does not have to be preceded by the --search option. The default value is 5 (seconds).

-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).

-v

None

Displays the execution log.

-V, --version

None

Displays the version of the ares-setup-device command.

-h, --help

None

Displays the help of the ares-setup-device command.

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: File name 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.

 

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.

TIMEOUT

Timeout value for device searching (unit: second).

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 CLI usage:

Listing target devices

ares-setup-device --list

name        deviceinfo               connection   
---------   --------------------     ------------
device      root@127.0.0.1:22        ssh          

 

Listing all details of target devices

ares-setup-device --listfull

[
    {
        "profile": "rpi",
        "name": "device",
        "deviceinfo": {
            "ip": "127.0.0.1",
            "port": "22",
            "user": "root"
        },
        "connection": [
            "ssh"
        ],
        "details": {
            "platform": "webos",
            "password": "",
            "description": "webOS Open Device"
        }
    }
]

 

Adding the target device (Target device name: target, Host address: 10.123.45.67, Port number: 22 User: root)

ares-setup-device --add target -i "host=10.123.45.67" -i "port=22" -i "username=root"

 

Adding the target device with JSON format (Target device name: target, Host address: 10.123.45.67, Port number: 22 User: root)

ares-setup-device --add target --info "{'host':'10.123.45.67', 'port':'22', 'username':'root'}"

 

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

-------- ------------------------ ----------

device root@127.0.0.1:22 ssh

** 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]

? Save? Yes

 

name deviceinfo connection

-------- --------------------------- ----------

device root@127.0.0.1:22 ssh

target root@10.123.45.67:22 ssh

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

-------- --------------------------- ----------

device root@127.0.0.1:22 ssh

target root@10.123.45.67:22 ssh

 

** 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

-------- --------------------------- ----------

device root@127.0.0.1:22 ssh

target root@10.123.45.67:9922 ssh

Success to modify a device!!

If you want to keep the previous value, press Enter without any value.

 

Removing the target device (Target device name: target)

ares-setup-device --remove target

To remove a target device, you only need to enter the name of the target device following the command.

 

Searching webOS devices

ares-setup-device --search


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.

Usages

ares-install [OPTION...] PKG_FILE

ares-install [OPTION...] --remove APP_ID

ares-install [OPTION...] --list|-l 

ares-install [OPTION...] --listfull|-F 

ares-install --device-list|-D

ares-install --version|-V

ares-install --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device on which the application should be installed.

-l, --list

None

Lists the installed apps on the specified target device. Use this option in conjunction with -d, --device option.

-F, --listfull

None

Lists installed applications with more detail. Use this option in conjunction with -d, --device option.

-D, --device-list

None

Lists all the available devices.

--remove 

APP_ID

Removes the specified app from the device.

-v

None

Displays the execution log.

-V, --version

None

Displays the version of ares-install command.

-h, --help

None

Displays the help of ares-install command.

Parameters

Parameter

Description

PKG_FILE

Specifies the path of the app package file.

APP_ID

ID of the app to remove from the device.

TARGET_DEVICE

Specifies the target device for installing or removing the app or viewing the list of installed apps.

Examples

Here are some examples of the CLI usage:

Listing available target devices

ares-install --device-list

 

Installing the app on the target device

ares-install --device target com.example.sampleapp_1.0.0_all.ipk

 

Listing apps which are installed on the target device

ares-install --device target --list

 

Removing the app from the target device

ares-install --device target --remove com.example.sampleapp


ares-launch

This command runs or terminates the application installed on the target device. This command can also display the list of applications running on the target device.

Usages

ares-launch [OPTION...] APP_ID

ares-launch [OPTION...] --close APP_ID

ares-launch [OPTION...] --running|-r

ares-launch --version|-V

ares-launch --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device where the web application is installed.

--close

APP_ID

Terminates application on the target device.

-r, --running

None

Lists applications which are running on the target device.

-p, --params

PARAMS

Launches a web application with specified parameters.

-v

None

Displays the execution log.

-V, --version

None

Displays the version of the ares-launch command.

-h, --help

None

Displays the help of the ares-launch command.

Parameters

Parameter

Description

APP_ID

ID of the application to run or terminate.

APP_DIR

Specifies the directory of the application on the host machine to launch without installation.

TARGET_DEVICE

Specifies the target device on which the application is installed.

PARAMS

Specifies the parameters which are used on web 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:

Running the application installed on the target device

ares-launch --device target com.example.sampleapp

 

Running the application with url parameter

ares-launch --device target com.example.sampleapp --params "{'url':'webosose.org'}"

When you use a parameter, web app will receive the parameter with the webOSLaunch event. For more detailed information on the webOSLaunch event, see App Lifecycle.

 

Listing applications running on the target device

ares-launch --device target --running

 

Terminating application currently running

ares-launch --device target --close com.example.sampleapp


ares-inspect

This command provides Web Inspector and Node Inspector. Web Inspector and Node Inspector run in a web browser on the host machine. Each inspector displays the run-time information of the web application and JS services, respectively.

Usages

ares-inspect [OPTION...] [--app|-a] APP_ID

ares-inspect [OPTION...] --service|-s SERVICE_ID

ares-inspect --version|-V

ares-inspect --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device where the application is installed.

-a, --app

APP_ID

Specifies the application to run with Web Inspector.

-s, --service

SERVICE_ID

Specifies the JS service to run with Node Inspector.

-o, --open

None

Opens the default browser of the host machine.

Web Inspector and Node Inspector work 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).

-v

None

Displays the execution log.

-V, --version

None

Displays the version of the ares-inspect command.

-h, --help

None

Displays the help of the ares-inspect command.

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 Inspector.

TARGET_DEVICE

Specifies the target device on which the application is installed.

Examples

Here are some examples of the different uses:

Running the Web Inspector for an application

ares-inspect --device target --app com.example.sampleapp

 

Running the Node Inspector for a JS service

ares-inspect --device target --service com.example.sampleapp.sampleservice


ares-server

This command runs a web server for testing local file. The web server will run on the given path. You can terminate the web server with Control-C (in Windows, Linux) or Command-C (in Mac OS).

Usages

ares-server [OPTION...] APP_DIR

ares-server --version|-V

ares-server --help|-h

Options

Option

Parameter

Description

-o, --open

None

Opens the default browser of the host machine.

-v

None

Displays the execution log.

-V, --version

None

Displays the version of the ares-server command.

-h, --help

None

Displays the help of the ares-server command.

Parameters

Parameter

Description

APP_DIR

Specifies the directory of the application to be published on the web server.

Examples

Here are some examples of the different uses:

Running the Web Server in a source directory

ares-server ./source

 

Running the Web Server with browser

ares-server ./source --open


ares-shell

This command opens a shell of a target device and executes shell commands in the target device.

Usages

ares-shell -d TARGET_DEVICE

ares-shell -d TARGET_DEVICE -r CMD

ares-shell --device-list|-D

ares-shell --version

ares-shell --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device.

-r, --run

CMD

Specifies a command executed in the target device.

-D, --device-list

None

Lists available target devices.

-V, --version

None

Displays the version of the ares-shell command.

-h, --help

None

Displays the help of the ares-shell command.

Parameters

Parameter

Description

CMD

Specifies a command executed in the target device.

TARGET_DEVICE

Specifies the target device.

Examples

Here are some examples of the different uses:

Opening the remote shell of the target device

ares-shell --device target

 

Executing a command inside the shell of the target device

ares-shell --device target -r "pwd"

ares-shell --device target -r "echo hello webOS"


ares-push

This command pushes file(s) from a host machine to a target device.

Usages

ares-push [OPTION...] SOURCE DESTINATION

ares-push --device-list|-D

ares-push --version|-V

ares-push --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device that you want to copy the file(s) to.

-D, --device-list

None

Lists available target devices.

-v

None

Displays the execution log.

-

V, --version

None

Displays the version of the ares-push command.

-h, --help

None

Displays the help of the ares-push command.

-i, --ignore

None

Does not display detailed messages of the ares-push result.

Parameters

Parameter

Description

SOURCE

Specifies the file/directory path of the host machine.

DESTINATION

Specifies the file/directory path of the target device.

TARGET_DEVICE

Specifies the target device that you want to copy the file(s) to.

Examples

Here are some examples of the different uses:

Listing available targets

ares-push --device-list

 

Pushing contents of a specific directory from the host machine to the target device

ares-push --device target /home/username/foo /home/username/foo

 

Pushing a file from the host machine to the target device

ares-push --device target /home/username/foo.txt  /home/username/foo.txt


ares-pull

This command pulls file(s) from a target device to a host machine.

Usages

ares-pull [OPTION...] SOURCE DESTINATION

ares-pull --device-list|-D

ares-pull --version|-V

ares-pull --help|-h

Options

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies the target device that you want to copy the file(s) from.

-D, --device-list

None

Lists available target devices.

-v

None

Displays the execution log.

-

V, --version

None

Displays the version of ares-pull command.

-h, --help

None

Displays the help of ares-pull command.

-i, --ignore

None

Does not display detailed messages of ares-pull result.

Parameters

Parameter

Description

SOURCE

Specifies the file/directory path of the target device.

DESTINATION

Specifies the file/directory path of the host machine.

TARGET_DEVICE

Specifies the target device that you want to copy the file(s) from.

Examples

Here are some examples of the different uses:

Listing available target devices

ares-pull --device-list

 

Pulling contents of a specific directory from the target device to the host machine

ares-pull --device target /home/username/foo /home/username/foo

 

Pulling a file from the target device to the host machine

ares-pull --device target /home/username/foo.txt  /home/username/foo.txt



Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.