Command-Line Interface User Guide

Command-Line Interface (CLI) of webOS Open Source Edition (OSE) provides a collection of commands used for creating, packaging, installing, and launching web apps in the command line environment. CLI allows you to develop and test apps without having to use a specific IDE.

Key Features

CLI provides the following key features:

• Project creation
  • Provides standard project templates for webOS OSE web apps
  • Provides a list of available templates
  • Generates a project for an app and sets up basic information of an app
• Web app 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 a project
  • Generates app installation files for debugging
• Target device management
  • Provides a list of target devices
  • Adds, modifies, and removes target devices
• Web app installation
  • Installs apps on the target device
  • Provides a list of apps installed on the target device
  • Removes selected apps from the target device
• Web app launching/closing
  • Launches selected apps
  • Closes apps that are running
  • Provides the list of apps running on the target device
• Web app debugging
  • Enables Web Inspector for debugging web apps
  • Enables Node's Inspector for debugging JavaScript services
  • Provides web app information
  • Provides JavaScript service information

Installing CLI

This section describes how to install CLI on your host machine.

Download the Package

First, download the CLI package for your operating system from the SDK download page.

Unzip 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\bin
• Linux & macOS: ares-cli/bin

Set the Path

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

Windows

If you unzipped the package under C:\, the CLI commands would be located in C:\ares-cli\bin. You need to add the directory to the environment variable using one of the commands below in a command shell.

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

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

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

Linux & macOS

There are many ways to set the environment variable in Linux and macOS. 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 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

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.

CLI Commands

The following table shows the available CLI commands.

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

Parameters

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

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

Parameters

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

ares-package sampleApp sampleService

Creating a package file with multiple external JS services

ares-package sampleApp sampleServiceA sampleServiceB

Creating a package file with 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 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

Parameters

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

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

Removing the target device (Target device name: target)

ares-setup-device --remove target

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

Parameters

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

Parameters

Examples

Here are some examples of the different uses:

Launching the application installed on the target device

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

Launching the application with url parameter

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

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 enables Web Inspector or Node's Inspector. Each inspector displays the run-time information of a web application or a JS service, 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

Parameters

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's Inspector for a JS service

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

ares-server

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.

Usages

ares-server [OPTION...] APP_DIR

ares-server --version|-V

ares-server --help|-h

Options

Parameters

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

Parameters

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

Parameters

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

Parameters

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