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 lets you develop and test apps or services without using any IDE.

Note
The npm package name of the CLI has been changed (from @webosose/ares-cli to @webos-tools/cli) since v3.0.2 (March 4, 2024). See How to Install.

Key Features

CLI provides necessary functionality throughout the entire web app development process, from app creation to debugging and testing. The following figure shows CLI commands that can be used during each stage of the development process.

Development Workflow with CLI

  • Creating Apps and Services
    • 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
  • Packaging Apps and Services
    • 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
  • Managing Target Devices
    • Provides a list of target devices
    • Adds, modifies, and removes target devices
  • Installing Apps and Services
    • 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
  • Launching and Closing Apps
    • Launches selected apps
    • Closes apps that are running
    • Provides the list of apps running on the target device
  • Debugging/Testing Apps and Services
    • Enables Web Inspector for debugging web apps
    • Enables Node’s Inspector for debugging JavaScript services
    • Provides web app information
    • Provides JavaScript service information
    • Shows or saves logs of webOS OSE apps and services
  • Providing Target Device Information
    • Provides system information
    • Provides screen capture
    • Supports monitoring device’s resource usage

System Requirements

Operating Systems

Required version for each operating system are as follows:

OS

Requirement

Linux

Ubuntu 20.04 LTS 64-bit

macOS

Mac OS X 10.13 High Sierra or higher

Windows

Windows 10 64-bit

Software Tools

  • Node.js (Use v14.15.1 to v16.20.2)
  • npm

How to Install

CLI can be installed using Node Package Manager (npm).

Step 01. Installing npm

Before installing the CLI, ensure that Node.js and npm are installed on your system. If they are not installed, refer to the following instructions.

Node.js

  1. Visit the official Node.js website and download the recommended version for your operating system.
  2. Run the installer and follow the installation instructions.
  3. When finished, verify the installation by checking its version.
node -v

npm

The npm is included with the Node.js, so if you have successfully installed Node.js, you already have npm available for use.

Execute the following command to verify if the npm is available on your system.

npm -v

Step 02. Installing CLI

Caution

If the CLI is already installed globally, we highly recommend uninstalling the previous CLI globally.

# Uninstall the CLI globally
$ npm uninstall -g @webosose/ares-cli
# Verify whether uninstalled the previous CLI
$ ares --version
ares: command not found

Execute the following command in a terminal, using the -g option to install the CLI globally. For Linux and macOS users, the sudo privilege might be required.

npm install -g @webos-tools/cli

Verify the installation by checking its version. Check if the version matches with the latest version of CLI npm package.

ares --version

Step 03. Setting Up the OSE Profile

CLI supports multi-webOS platforms since v3.0.2 (default profile: tv). To use the CLI on webOS OSE, you MUST change your profile to ose.

To set up the profile, enter the following command:

$ ares-config --profile ose

How to Use

With the CLI, you can develop various types of external apps or services. For detailed instructions, refer to the each tutorial.

Development Type

Tutorial

External Web Apps

See the Developing External Web Apps.

External JS Services

See the Developing External JS Services.

External QML Apps

See the Developing External QML Apps.

External Native Apps

See the Developing External Native Apps.

External Native Services

See the Developing External Native Services.

CLI Commands

The following table shows the available CLI commands.

Commands

Descriptions

ares-config

Configures webOS CLI.

ares

Provides the help menu for using the ares commands.

ares-generate

Creates a webOS OSE app or service from templates.

ares-package

Packages the app or services into a package file.

ares-setup-device

Manages the target devices.

ares-install

Installs the app or service on the target device.

ares-launch

Launches or terminates the app.

ares-inspect

Enables Web Inspector or Node's Inspector for debugging web app or JS service.

ares-server

Runs the Web server for testing local app file.

ares-shell

Executes shell commands on 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.

ares-device

Displays the device information.

ares-log

Shows or saves logs of webOS OSE apps or services.

ares-config

This command configures the CLI profile. You can change the profile at any time.

History

Version

Changes

v3.0.2

Added in.

Usages

ares-config

ares-config --profile|-p DEVICE_PROFILE

ares-config --profile-details|-c

ares-config --version|-V

ares-config --help|-h

Options

Option

Parameter

Description

-p, --profile

DEVICE_PROFILE

Specifies the CLI profile.

-c, --profile-details

None

Prints current configured profile.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

DEVICE_PROFILE

A profile of the target device. Possible values are as follows:

  • tv (default, for webOS TV)
  • ose

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Configure profile for platform (ose)

    ares-config -p ose
    
  • Currently configured profile

    ares-config -c
    

ares

This command provides the help menu for using the ares commands.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

Usages

ares

ares [OPTION...]

ares --version|-V

ares --help|-h

Options

Option

Parameter

Description

-l, --list

None

Lists all the ares commands.

--[COMMAND]

None

Prints help messages of COMMAND.

COMMAND is entered using postfix of the ares commands. For more details, see Examples.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Listing all the ares commands

    ares -l
    
  • Displaying the help menu for the ares-install command.

    ares --install
    

ares-generate

This command creates a webOS OSE app or service from a template. ares-generate displays a list of available templates for a web app, JS services, and webOS OSE configuration files.

History

Version

Changes

v2.3.1

Supports the --level option.

v2.1.0

Updates requiresPermissions in the appinfo.json file.

Caution
Template files generated by CLI v2.0.3 or older are not compatible with webOS OSE 2.10.0 or higher.

v1.11.0

Updates the properties of the appinfo.json file.

v1.6.4

Added in.

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

Option

Parameter

Description

-t, --template

TEMPLATE

Sets the template to be created. Available templates are as follows:

  • webapp (default)
  • hosted_webapp
  • webappinfo
  • js_service
  • jsserviceinfo
  • icon
  • qmlapp
  • qmlappinfo

For more information about each template, see Parameters.

-l, --list

None

Lists the available templates.

-p, --property

PROPERTY

Sets the properties of webOS OSE configuration files.

-s, --servicename

SERVICE_NAME

Specifies the JS service ID.

-f, --overwrite

None

Allows overwriting the existing files.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

APP_DIR

A directory to store the created app

If the directory doesn't exist, the directory will be created while executing the command.

SERVICE_DIR

A directory to store the created service

If the directory doesn't exist, the directory will be created while executing the command.

PROPERTY

Properties in the format of "key=value" or a JSON-type string: "{'key1':'value1', 'key2':'value2', ...}"

For more details, see appinfo.json and services.json.

TEMPLATE

A template to use when creating an app or a service (default value: webapp)

Template Name

Brief Description

webapp (Default)

Web app template for webOS OSE

hosted_webapp

Hosted web app template for webOS OSE

webappinfo

Creates an appinfo.json file for a web app.

js_service

JS service template for webOS OSE

jsserviceinfo

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

icon

Creates an app icon file. Required size is 80 x 80 (pixels).

qmlapp

QML app template for webOS OSE

qmlappinfo

Creates an appinfo.json file for a QML app.

SERVICE_NAME

The ID of a service

This ID should be a sub-domain of the app ID to which the service belongs. For more details, see Examples.

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Listing the templates (web application templates)

    ares-generate -l
    
  • Creating a web application using the default template in the ./sampleApp directory

    ares-generate ./sampleApp
    
  • Creating a web application with a custom app ID in the ./sampleApp directory

    ares-generate -p "id=com.example.sampleapp" ./sampleApp
    
  • Creating a JS service with a custom service ID in the ./sampleService directory (App ID: com.example.sampleapp)

    ares-generate -t js_service -s com.example.sampleapp.sampleservice ./sampleService
    
    Note
    The service ID should be a sub-domain of the app ID to which the service belongs.
  • Creating a web app in the ./sampleApp and setting properties with a JSON-type 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 or a JS service into a package file (.ipk) which is stored in a specified directory. This command also analyzes the package file.

History

Version

Changes

v2.3.1

Supports the --info, --info-detail, and --level options.

v1.12.0

Stops to support Enyo features.

v1.6.4

Added in.

Usages

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

ares-package --version|-V

ares-package --help|-h

Options

Option

Parameter

Description

-c, --check

None

Checks whether the appinfo.json file exists or not.

If the appinfo.json file does not exist, warning messages appear. This option does not make the package file.

-o, --outdir

OUT_DIR

Specifies a directory where the package file is created.

-e, --app-exclude

EX_DIR

Excludes directories or files when you package the source code. For more details on how to use this option, see Examples.

-r, --rom

None

Previews a directory hierarchy of an app when the app is installed.

This option creates a usr directory in the current directory rather than an .ipk file. The hierarchy of the usr directory is the same as the hierarchy when the .ipk file is actually installed on the target device.

--info

PACKAGE_FILE

Analyzes the package.

This option cannot be used in conjunction with other options.

--info-detail

PACKAGE_FILE

Analyzes the package with more details.

This option cannot be used in conjunction with other options.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

APP_DIR

The directory where the app's appinfo.json file is located

SERVICE_DIR

The directory where the service's services.json file is located

OUT_DIR

The directory where the package file (.ipk) is to be created

If this parameter is not specified, the package file is created in the current directory.

EX_DIR

A directory or file to be excluded from the package file (.ipk)

You can use common pattern expression such as wildcard (*).

PACKAGE_FILE

A webOS package file (.ipk)

This package file must be packaged with CLI beforehand.

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Creating a package file from the ./sampleApp directory and outputting it in the working directory

    ares-package sampleApp
    
  • Creating a package file from the ./sampleApp directory and outputting it in the ./output directory

    ares-package -o output sampleApp
    
  • Creating a package file except for the testCode1 directory (includes its subdirectories), README.md, and all .txt files

    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
    
  • Analyzing the package file

    ares-package -i ~/projects/packages/com.examples.app_1.0_all.ipk
    
  • Analyzing the package file with more details

    ares-package -I ~/projects/packages/com.examples.app_1.0_all.ipk
    

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. Without any option, this command runs in the interactive mode.

History

Version

Changes

v2.3.1

Supports the --level option.

v2.2.0

Updates a naming rule for the DEVICE_NAME parameter.

v1.12.0

Supports the --default option.

v1.6.4

Added in.

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 --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. For more details, see Examples.

-m, --modify

TARGET_NAME

Modifies target device's information except a target device's name. For more details, see Examples.

-i, --info

DEVICE_INFO

Sets information for the target device. For more details on DEVICE_INFO, see Parameters.

-r, --remove

TARGET_NAME

Deletes a registered target device.

-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 details in the JSON format.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

DEVICE_INFO

Information of the target device in the format of "key=value" or a JSON-type string: "{'key1':'value1', 'key2':'value2', ...}". For more details, see Examples.

The available keys are as follows:

  • name: Target device name

    • The target device name should consist of letters, numbers, hyphen (-), underscore (_), and number sign (#) and start with letters or underscore (_).

  • description: Target device description

  • host: Target device host address

  • port: Target device port number

  • username: Username for accessing the target device

    • 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

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

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
    
  • 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 a target device as the 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 a target device with a JSON-type string (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 a 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 use the default values or an empty value, press the Enter key without any input.
  • Modifying a target device (target device name: target, port number: 9922)

    ares-setup-device --modify target -i "port=9922"
    
  • Modifying a 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 use the preset values, press the Enter key without any input.
  • Setting a target device as the default device

    ares-setup-device --default target
    
  • Removing a target device

    ares-setup-device --remove target
    

ares-install

This command installs an packaged app on the target device. You can also check the list of installed apps or remove them with this command.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

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

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-l, --list

None

Lists installed applications on the target device.

-F, --listfull

None

Lists the installed applications on the target device with more details.

-r, --remove

APP_ID

Removes an application on the target device.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

PKG_FILE

The path of the package file (.ipk)

APP_ID

The ID of an app (ex. com.webos.exampleapp)

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Listing available target devices

    ares-install --device-list
    
  • Installing an app on the target device

    ares-install --device target com.example.sampleapp_1.0.0_all.ipk
    
  • Listing apps installed on the target device

    ares-install --device target --list
    
  • Removing an 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.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.12.0

Supports the --hosted option.

v1.11.0

Supports the --display option.

v1.6.4

Added in.

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

Option

Parameter

Description

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

--close

APP_ID

Terminates an application on the target device.

-r, --running

None

Lists applications that are running on the target device.

-dp, --display

DISPLAY_ID

Launches an application on a specified display.

-p, --params

PARAMS

Launches an application with specified parameters. For more details, see PARAMS in Parameters and Examples.

-H, --hosted

APP_DIR

Runs an app without installing it.

This option launches a dummy app (ID: com.sdk.ares.hostedapp) on the target device. To close this app, use the --close option with com.sdk.ares.hostedapp as an app ID.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

APP_ID

The ID of an app (ex. com.webos.exampleapp)

APP_DIR

An app directory to preview

DISPLAY_ID

The ID of a display to launch

It should be an integer type. (Use 0 for the primary display and 1 for the secondary display.)

TARGET_DEVICE

The name of a target device

PARAMS

Parameters which are used on application launching

This parameters should be a JSON-type string: "{'param1':'value1', 'param2':'value2 which contains spaces', ...}". See also params in the launch method.

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

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 parameters on a web app, the web app will receive the parameters through 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
    
  • Terminating application on the primary display

    ares-launch --device target --close com.example.sampleapp --display 0
    
  • 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.

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 on how to set up the username, see DEVICE_INFO of ares-setup-device.
    • Execute the Web Browser app and go to http://useragentstring.com.
    • Visit the webOS OSE GitHub and find a Chromium repository of the latest version. Then see src/chrome/VERSION file.
  • To download old builds of Chrome/Chromium, visit the Chromium Project website.

History

Version

Changes

v2.4.0

Updates guide messages of the --service option.

v2.3.1

Supports the --level option.

v2.0.2

Supports the --display option.

v1.6.4

Added in.

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

Option

Parameter

Description

-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. This option is only available for Web Inspector, thus can be used with the -a, --app option only.

Web Inspector works in the Blink-based web browsers (e.g., Chrome or Opera) only. If your default browser is not the Blink-based browsers, such as Safari or Internet Explorer, you must re-open the inspector page in the Blink-based browsers.

Note
To connect to Node’s Inspector, you should use one of the Node’s Inspector clients, such as Chrome DevTools or Visual Studio Code. For more information, see Inspector Clients.

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-dp, --display

DISPLAY_ID

Launches an application and opens Web Inspector on a specified display.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

APP_ID

The ID of an app (ex. com.webos.exampleapp)

SERVICE_ID

The ID of a JS service (ex. com.webos.exampleapp.service)

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

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 local files. The web server will run on the given path. You can terminate the web server by pressing Control+C on the shell prompt.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

Usages

ares-server [OPTION...] APP_DIR

ares-server --version|-V

ares-server --help|-h

Options

Option

Parameter

Description

-p, --port

PORT

Specifies the port to be used. (Default: random)

-o, --open

None

Opens the default browser of the host machine.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

APP_DIR

The directory where the application's appinfo.json file is located

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

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 the default browser

    ares-server ./source --open
    

ares-shell

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

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

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 a target device to connect.

If this option is not specified, the default target device is connected.

-r, --run

CMD

Executes shell commands on the target device.

-D, --device-list

None

Lists all the target devices.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

CMD

Shell commands to be executed on the target device

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Opening a 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 files from a host machine to a target device.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

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 a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-i, --ignore

None

Prints the short version of output messages.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

SOURCE

A file/directory path of the host machine

DESTINATION

A file/directory path of the target device

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Listing available target devices

    ares-push --device-list
    
  • Pushing a directory from the host machine to the target device

    ares-push --device target /host/directory/ /target/directory/
    
  • Pushing a file from the host machine to the target device

    ares-push --device target /host/directory/file.txt /target/directory/file.txt
    

ares-pull

This command pulls the files from a target device to a host machine.

History

Version

Changes

v2.3.1

Supports the --level option.

v1.6.4

Added in.

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 a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-i, --ignore

None

Prints the short version of output messages.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

SOURCE

A file/directory path of the target device

DESTINATION

A file/directory path of the host machine

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Listing available target devices

    ares-pull --device-list
    
  • Pulling a directory from the target device to the host machine

    ares-pull --device target /target/directory/ /host/directory/
    
  • Pulling a file from the target device to the host machine

    ares-pull --device target /target/directory/file.txt /host/directory/file.txt
    

ares-device

This command displays the information of the target device.

History

Version

Changes

v2.4.0

Supports the Node.js version in the --system-info result.

v2.3.1

Supports the --resource-monitor and the --level options.

v2.1.0

Supports the --capture-screen option.

v2.0.0

ares-device-info is replaced by ares-device.

v1.13.0

Added in.

Usages

ares-device [OPTION...] [TARGET_DEVICE]

ares-device --device-list|-D

ares-device --version|-V

ares-device --help|-h

Options

Option

Parameter

Description

-i, --system-info

None

Displays the device system information.

-r, --resource-monitor

None

Monitors resource usage.

-l, --list

None

Monitors resource usage of running apps and services.

Use this option in conjunction with the -r, --resource-monitor option.

-id, --id-filter

ID

Monitors resource usage of an app or service.

Use this option in conjunction with the -r, --resource-monitor option.

-t, --time-interval

SECONDS

Sets the monitoring interval (seconds).

Use this option in conjunction with the -r, --resource-monitor option.

-s, --save

CSV_FILE

Saves resource usage data to CSV_FILE.

Use this option in conjunction with the -r, --resource-monitor option.

-c, --capture-screen

OUTPUT_PATH

Captures screen and saves the captured image to the host machine.

-dp, --display

DISPLAY_ID

Specifies DISPLAY_ID.

Use this option in conjunction with the -c, --capture-screen option.

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-h, --help

None

Prints help messages.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

TARGET_DEVICE

The name of a target device

ID

The ID of an app or service whose resource usage be displayed

SECONDS

A period for monitoring the resource usage (seconds)

CSV_FILE

A file name or path to save the resource usage data

The file format can be only .csv.

OUTPUT_PATH

A file or directory path of the host machine to save captured file

DISPLAY_ID

The ID of a display to be captured

It should be an integer type. (Use 0 for the primary display and 1 for the secondary display.)

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Displaying the system information of the target device

    ares-device --system-info --device target
    
  • Displaying resource usage

    ares-device --resource-device --device target
    
  • Displaying resource usage periodically and saving them to a CSV file

    ares-device --resource-device --save resource.csv --time-interval 1 --device target
    
  • Displaying resource usage of running apps and services

    ares-device --resource-device --list --time-interval 3 --device target
    
  • Displaying resource usage of specified running app

    ares-device --resource-device --id-filter com.examples.app --time-interval 5 --device target
    
  • Capturing the display 1 and saves it as screen.png

    ares-device --capture-screen screen.png --display 1 --device target
    

ares-log (journal)

This command shows, filters, and saves logs collected by journald.

Note
To display logs and help messages properly, you must set the logging daemon of CLI to same as that of the target device. For more details on how to check and change the logging daemon, see --current-daemon and --switch-daemon in Options.

For more information about analyzing journal logs, see Viewing Logs when journald is Enabled.

History

Version

Changes

v2.3.1

Supports --current-daemon, --switch-daemon, and --level options.

v2.2.0

Added in.

Usages

ares-log [OPTION...] 

ares-log [OPTION...] --follow|-f

ares-log [OPTION...] --reverse|-r

ares-log [OPTION...] --lines|-n LINE

ares-log [OPTION...] --boot|-b

ares-log [OPTION...] --dmesg|-k

ares-log [OPTION...] --priority|-p PRIORITY

ares-log [OPTION...] --pid|-pid PID

ares-log [OPTION...] --since|-S DATE

ares-log [OPTION...] --until|-U DATE

ares-log [OPTION...] --unit-list|-ul

ares-log [OPTION...] --unit|-u UNIT

ares-log [OPTION...] --file-list|-fl

ares-log [OPTION...] --file|-file JOURNAL_FILE

ares-log --device-list|-D

ares-log --version|-V

ares-log --help|-h

Options

Option

Parameter

Description

-cd, --current-daemon

None

Checks the current logging daemon of CLI and the target device.

-sd, --switch-daemon

LOGGING_DAEMON

Changes the current logging daemon of CLI.

-o, --output

OUTPUT_MODE

Changes the log format.

-s, --save

SAVED_FILE

Saves logs into a file.

-dp, --display

DISPLAY_ID

Selects the display to show logs.

Use this option in conjunction with the unit and unit-list options.

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the target devices.

-h, --help

None

Prints help messages.

Note
Help messages vary depending on the current logging daemon of CLI. Before using this option, make sure you set the right daemon you want.

-V, --version

None

Prints the version of CLI.

-v

None

Prints verbose output.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

LINE

The number of lines to show

PRIORITY

A priority level of logs

For more details, see Filter Messages by Priority.

PID

The ID of a process to check logs

DATE

A timestamp in the format: YYYY-MM-DD hh:mm:ss

UNIT

Unit name to check logs

To get the list of available UNIT values, use the --unit-list option.

JOURNAL_FILE

The name of a journal files

To get the list of available JOURNAL_FILE values, use the --file-list option.

LOGGING_DAEMON

A name of the logging daemon (e.g., journald, pmlogd)

OUTPUT_MODE

A format of log messages

For more details, see Format Logs.

SAVED_FILE

A file name or path to save logs

DISPLAY_ID

The ID of a display to check logs

It should be an integer type. (Use 0 for the primary display and 1 for the secondary display.)

TARGET_DEVICE

The name of a target device

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Checking the current logging daemon

    ares-log -cd -d DEVICE
    
  • Changing the current logging daemon to pmlogd

    ares-log -sd pmlogd -d DEVICE
    
  • Following the journals

    ares-log -f -d DEVICE
    
  • Displaying the number of journal entries to show

    ares-log -n 10 -d DEVICE
    
  • Displaying logs between the two DATEs

    ares-log -S 2021-03-18 21:38:00 --until 2021-03-18 21:39:00 -d DEVICE
    
  • Displaying a list of the stored journal files

    ares-log -fl -d DEVICE
    
  • Displaying stored logs from system.journal in the JSON format

    ares-log -file system.journal -o json -d DEVICE
    
  • Displaying logs of the specified process ID and saving them to a log file

    ares-log -pid 1735 -s pid_1735.log -d DEVICE
    
  • Displaying logs of the specified unit

    ares-log -u sam -d DEVICE
    

ares-log (pmlog)

This command shows, filters, and saves logs collected by pmlogd.

Note
To print logs and help messages properly, you must set the logging daemon of CLI to same as that of the target device. For more details on how to check and change the logging daemon, see --current-daemon and --switch-daemon in Options.

For more information about analyzing pmlog logs, see Viewing Logs when pmlogd is Enabled.

History

Version

Changes

v2.3.1

Added in.

Usages

ares-log [OPTION...] 

ares-log [OPTION...] --follow|-f

ares-log [OPTION...] --lines|-n LINE

ares-log --device-list|-D

ares-log --version|-V

ares-log --help|-h

Options

Option

Parameter

Description

-cd, --current-daemon

None

Checks the current logging daemon of CLI and the target device.

-sd, --switch-daemon

LOGGING_DAEMON

Changes the current logging daemon of CLI.

-id, --id-filter

ID

Shows logs from a app or service of ID.

-s, --save

SAVED_FILE

Saves logs into a file.

-cl, --context-list

None

Lists the contexts and those log level.

-sl, --set-level

CONTEXT CONTEXT_LEVEL

Sets the log level of CONTEXT to CONTEXT_LEVEL.

-d, --device

TARGET_DEVICE

Specifies a target device to connect.

If this option is not specified, the default target device is connected.

-D, --device-list

None

Lists all the available devices.

-h, --help

None

Prints help messages.

Note
Help messages vary depending on the current logging daemon of CLI. Before using this option, make sure you set the right daemon you want.

-V, --version

None

Prints the version of CLI.

-v

None

Displays the verbose logs.

--level

LEVEL

Sets the level of logs as LEVEL and prints the logs.

Parameters

Parameter

Description

LINE

The number of lines to show

LOGGING_DAEMON

A name of the logging daemon (e.g., journald, pmlogd)

ID

The ID of an app or service

SAVED_FILE

A file name or path to save logs

CONTEXT

Name of context

CONTEXT_LEVEL

A priority of specific context logs (e.g., info, notice, warning, err)

LEVEL

A priority of logs (e.g., silly, verbose, info, warn, error)

Examples

Here are some examples of the different uses:

  • Checking the current logging daemon

    ares-log -cd -d DEVICE
    
  • Changing the current logging daemon to journald

    ares-log -sd journald-d DEVICE
    
  • Following pmlog

    ares-log -f -d DEVICE
    
  • Setting the number of pmlog entries to show

    ares-log -n 10 -d DEVICE
    
  • Following logs and saving them to a log file

    ares-log -f -s follow.log -d DEVICE
    
  • Following logs of an app

    ares-log -f -id com.examples.app -d DEVICE
    
  • Following logs of a service and saving them to a log file

    ares-log -f -id com.examples.app.service -s service.log -d DEVICE
    
  • Showing context list of the target device

    ares-log -cl -d DEVICE
    
  • Setting the log level for a specific context to debug

    ares-log -sl WAM debug -d DEVICE
    

Contents