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 apps or services in the command line environment. CLI allows you to develop and test apps or services without having to use a specific 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

Required version for each operating system are as follows:

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

Usages

ares-generate [OPTION...] APP_DIR

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

ares-generate --list|-l

ares-generate --version|-V

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 a custom app ID in ./sampleApp directory

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

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

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

  Note
  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 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|-V

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

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 [OPTION...] --default|-f [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  profile
  ------------------ ------------------------ ----------- -------
  emulator (default) developer@127.0.0.1:6622 ssh         ose
  

• 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 as a default 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" -i "default=true"
  

• 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', 'default':true}"
  

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

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 --device-list|-V

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'}"
  

  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.

• Launching the application on the primary display

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

• Listing applications running on the target device

  ares-launch --device target --running
  

• Terminating application currently running

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

• Running the app without installation

  ares-launch --device target --hosted 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 --device-list|-D

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 a 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 <hostPath>/tmpDir <targetPath>/tmpDir
  

• Pushing a file from the host machine to the target device

  ares-push --device target <hostPath>/foo.txt <targetPath>/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 <targetPath>/tmpDir <hostPath>/tmpDir
  

• Pulling a file from the target device to the host machine

  ares-pull --device target <targetPath>/foo.txt <hostPath>/foo.txt