webos-tools@webos-tools/cli
@webos-tools/cli is a Command-Line Interface (CLI) for webOS. It provides a collection of commands for creating, packaging, installing, and launching webOS apps or services in a command-line environment. With @webos-tools/cli, you can develop and test your app or service without using any IDE.
Announcement
We moved here from @webosose/ares-cli. In the future, we plan to develop and maintain a single webOS CLI here to support webOS.
We are releasing a single CLI that supports both webOS OSE and webOS TV through this released CLI (v3.0.0). You can switch to CLI for OSE or TV by installing one CLI and changing only the profile. For more details, see Profile Settings.
From the released CLI (v3.1.2) we integrated CLI commands for webOS APOLLO. You can switch to CLI for APOLLO by changing only the profile to apollo.
From the released CLI (v3.2.0) we integrated CLI commands for webOS SIGNAGE. You can switch to CLI for SIGNAGE by changing only the profile to signage.
Installation
[!IMPORTANT] If @webosose/ares-cli is installed globally, uninstall it before install globally @webos-tools/cli.
# Uninstall globally @webosose/ares-cli $ npm uninstall -g @webosose/ares-cli# Check whether uninstall @webosose/ares-cli $ ares -V ares: command not found
The @webos-tools/cli is installed using npm.
Note: @webos-tools/cli was tested on Node.js v14.15.1 and v16.20.2.
You can install @webos-tools/cli using the following command. We recommend installing it globally. For Linux and macOS, you might need the sudo command.
$ npm install -g @webos-tools/cliProfile Settings
You can change the profile to tv, ose, apollo or signage. The default profile is tv (webOS TV).
$ ares-config --profile ose
profile and config data is changed to oseYou can change the profile at any time while using the CLI by using the above command.
Compatibility
The release cycle of @webos-tools/cli is independent from that of webOS OSE or webOS TV. The latest CLI is compatible with the latest webOS OSE and webOS TV. So, we recommend using the latest version of CLI.
If you want to use previous version of CLI, check the compatibility table for each platform.
Command List
The following table shows a list supported commands. For more details, refer to user guides in Documentation.
| Command | Description | OSE | TV | APOLLO | SIGNAGE |
|---|---|---|---|---|---|
| ares-config | Configures webOS CLI. | v | v | v | v |
| ares | Displays the help information for ares commands. | v | v | v | v |
| ares-generate | Creates a webOS app or service from templates. | v | v | v | v |
| ares-package | Packages the app or services into a package file. | v | v | v | v |
| ares-setup-device | Manages the target devices. | v | v | v | v |
| ares-novacom | Command Line Tool to control the device. | | v | | v | ||
| ares-install | Installs the app or service on the target device. | v | v | v | v |
| ares-launch | Launches or terminates the app. | v | v | v | v |
| ares-inspect | Enables Web Inspector or Node's Inspector for debugging web app or JS service. | v | v | v | v |
| ares-server | Runs the Web server for testing local app file. | v | v | v | v |
| ares-shell | Executes shell commands in the target device. | v | | v | ||
| ares-push | Pushes file(s) from a host machine to a target device. | v | | v | ||
| ares-pull | Pulls file(s) from a target device to a host machine. | v | | v | ||
| ares-device | Displays the device information. | v | v | v | |
| ares-log | Shows or saves logs of webOS apps and services. | v | | v |
Documentation
For ose profile:
- How to use webOS OSE CLI, see the webOS OSE CLI User Guide.
- How to develop external Web/QML/Native apps or JS/Native services for webOS OSE, see the webOS OSE Tutorials.
For tv profile:
- How to use webOS TV CLI, see the webOS TV CLI Introduction.
- How to develop web apps or JS services for webOS TV, see the webOS TV Developer Guide.
For signage profile:
- How to use webOS Signage CLI, see the webOS Signage CLI Introduction.
- How to develop web apps or JS services for webOS Signage, see the webOS Signage Developer Guide.
Testing
You can test the @webos-tools/cli commands and their options to check their validity. Tests are performed by jasmine.
Prerequisites
- Turn on the webOS device.
- Check the IP address and SSH port number.
- (Only for webOS TV) Enable the developer mode. See App Testing with Developer Mode App
Performing the Test
The following table lists the default configurations for the test.
| Parameter | Value |
|---|---|
| profile | ose |
| device | emulator |
| ip | 127.0.0.1 |
| port | 6622 |
Test with default configurations.
$ jasmineor
$ jasmine --profile=ose --device=emulator --ip=127.0.0.1 --port=6622Test with specific configurations. (The port number can be omitted when using port 22.)
$ jasmine --profile=ose --device=webOSOSE --ip=192.168.0.12Test with specific port configurations.
$ jasmine --profile=ose --device=webOSOSE --ip=192.168.0.12 --port=24Test ares-generate command.
$ jasmine --profile=ose --device=webOSOSE --ip=192.168.0.12 --port=24 spec/jsSpec/ares-generate.jsTest the
tvprofile.passPhrasemust be entered as an input parameter. See Turning Developer Mode on.$ jasmine --profile=tv --device=webOSTV --ip=192.168.0.12 --port=9922 --passPhrase=AB12CD
Contributing
You can contribute your source codes to our repository.
The step-by-step guide is as follows:
- Fork the @webos-tools/cli repository. Make sure that you fork the whole repository.
- Create a new branch from the develop branch.
- Implement the source codes and
git pushthe changes to the new branch. - Create a pull request. When you write the description for the pull request, make sure you follow Pull Request Description Guidelines.
- Submit the pull request to the owner.
Pull Request Description Guide
The following is an example of the pull reqeust description
Change ares-device-info to ares-device
:Release Notes:
Expand the scope of ares-device-info command by changing its name
:Detailed Notes:
For now, the scope of the ares-device-info command seems to narrow,
so it is hard to add other options to the command (such as capture)
- Rename ares-device-info.js to ares-device.js
- Add --system-info and --session-info options
- Update ares-device TC
:Testing Performed:
1. All unit test passed
2. ESLint done
3. Check the below commands
$ ares-device
$ ares-device --system-info
$ ares-device --session-info
:Issues Addressed:
[ISSUE-1] Change ares-device-info to ares-device- Summary: Describe the summary of this pull request. Make sure you capitalize the first letter of the summary.
- Release Notes: Describe what this pull request implements.
- Detailed Notes: Describe the problems of this pull request and how to fix them.
- Testing Performed: Describe tests you performed.
- Unit test: Run CLI unit test via
jasmineon the target device or emulator and write the result. All unit tests must be passed. - ESlint: Run
eslinton @webos-tools/cli root directory and write the result. No warning or error would be allowed. - Detailed test steps for changes: Write commands that can test your changes. Make sure that maintainers can verify your changes using these steps.
- Unit test: Run CLI unit test via
- Issues Addressed: Write issue numbers and those summary.
Copyright and License Information
Unless otherwise specified, all content, including all source code files and documentation files in this repository are:
Copyright (c) 2020-2024 LG Electronics, Inc.
All content, including all source code files and documentation files in this repository except otherwise noted are:
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
SPDX-License-Identifier: Apache-2.0