App Management and Communication Tools

This page describes the command-line tools for package management vpm, lifecycle operations vlcm, and app communication. Access these tools through the device shell.

# For physical device (replace <Device Serial Number> with your actual device serial number):
kepler device shell --device <Device Serial Number>
Example: kepler device shell --device ABC000XYZ

# For Vega Virtual Device:
kepler device shell --device VirtualDevice

Package management

vpm commands

Manages packages and components on your device.

vpm --help
Package Manager Tool
Usage:
vpm list (packages  | components) [—category=<category>]... [—uri=<uri>]...
vpm info <id> [—package]
vpm install <path-to-package> [—force] [—stub]
vpm uninstall <package-id>

vpm list

Displays installed packages, apps, or components. Command: Parameters:

packages - Lists all installed packages
components - Lists all components
--category - (Optional) Filters by component category
--uri - (Optional) Filters by supported uniform resource identifiers (URI)

Example:

vpm list packages
// Output
package ids:
    com.amazondeveloper.test

vpm list components —category=com.amazondeveloper.category.games
// Output
components:
    com.amazondeveloper.category.games
    com.amazondeveloper.category.entertainment

vpm info

Displays manifest information for installed packages and their components. Command: Parameters:

id - Package ID or component ID
--package - (Optional) Shows only package information, regardless of whether a package or component ID is provided

Example package information:

vpm info com.amazondeveloper.test
// Output
id: com.amazondeveloper.test
title:Test Amazon Developer Package

Example component-specific information:

vpm info com.amazondeveloper.test.interactive
// Output
id: com.amazondeveloper.test.interactive
type: interactive
categories: com.amazon.category.samplepkg.component.examples
launch type: default

vpm install

Installs an app package (.vpkg) file from the device’s file system. To use this command, push the file to a specific folder on your device and run vpm install. The file must be in .vpkg format and must exist on the device before using vpm install. The vpm install command doesn’t support package installation over the network. Command: Parameters:

path-to-package - Full path to the .vpkg file
--force - (Optional) Forces installation regardless of conflicts

Example:

vpm install /tmp/test_x86_64.vpkg
// Output
Installing/Updating '/tmp/test_x86_64.vpkg' ...success

You can also use either kepler device install-app to install, or kepler run-kepler to install and run your app.

vpm uninstall

Removes an installed package from the system. Command: Parameter:

package-id - ID of the package to remove

Example:

vpm uninstall com.amazondeveloper.test
// Output
Uninstalling 'com.amazondeveloper.test' ...success

Lifecycle management

vlcm commands

Manages the lifecycle of running programs.

vlcm --help
Lifecycle Manager Tool
    Usage:
      vlcm terminate-app (--pkg-id <pkg-id> | --pid <pid>) [--force]
      vlcm launch-app <uri> [--new-container | --singleton]

vlcm list

Displays the status of all running components.

vlcm list
application                                type      pid     id    state       lifespan       timeout container                               launch args
com.amazon.lcm.stem.webview.main           S         2719    1     IDLE        PERMANENT      DEFAULT framework.slice/service                 <none>
com.amazon.lcm.stem.apl.main               S         2725    2     IDLE        PERMANENT      DEFAULT framework.slice/service                 <none>
com.amazon.lcm.stem.generic.main           S         3377    15    IDLE        PERMANENT      DEFAULT framework.slice/service                 <none>

* application - component id, defined in manifest.toml
* type - service (S), interactive (I), or task (T) also defined in manifest.toml
* pid - process id
* id - instance id
* state - lifecycle state
    * visible - component is running in the foreground
    * not_visible - component is running in the background
    * paused - component has paused execution and is now in the background
    * ready - component runs in the background, available for foreground use
    * idle - component runs in background, unavailable for foreground use
    * stopped - component has terminated
* lifespan - current lifecycle duration setting (can be changed at runtime)
* timeout - current timeout setting (can be changed at runtime)
* container - application process container (managed by system)
* launch args - query parameters passed in with the launch URI

vlcm terminate-app

Closes the app and requires a package-id or process id (pid). You can get the pid of your app by using the vlcm list command. Example:

vlcm terminate-app --pkg-id com.amazondeveloper.helloworld
# success
Stopping pkg: com.amazondeveloper.helloworld
# failure
Stopping pkg: com.amazondeveloper.helloworld
Failed to stop app

App communication

vmsgr send (preferred option)

Launches apps and sends messages using URI to communicate with Vega apps in the following ways:

Launch a lifecycle component
Send a broadcast message
Send a unicast message to a specific app

When launching an app, the URI must follow one of the supported addressing schemes. You can include additional information for your app by adding query parameters to the URI. Example:

vmsgr send pkg://com.amazondeveloper.test.main?extra=true
# Success: Message sent to component com.amazondeveloper.test.main

vmsgr send pkg://com.amazondeveloper.test.invalid
# Failure
Error: Failed to send message (-1): Component not found

vmsgr enforce-security

Enables security enforcement on specific packages for development and testing purposes only. Command: vmsgr enforce-security [options] Example:

vmsgr enforce-security --package com.amazondeveloper.test

For details, see Test with Access Controls.

vlcm launch-app

Launches an app using its URI. Unlike vmsgr send, vlcm launch-app option only launches apps. Command: Parameters:

uri: Package URI to launch (format: pkg://component-id)

Example:

vlcm launch-app pkg://com.amazondeveloper.test.main?extra=true
# success:
CLI: Launch URI: pkg://com.amazondeveloper.test.main?extra=true
# failure:
CLI: Failed to launch (-1): pkg://com.amazondeveloper.test.invalid

​Package management

​vpm commands

​vpm list

​vpm info

​vpm install

​vpm uninstall

​Lifecycle management

​vlcm commands

​vlcm list

​vlcm terminate-app

​App communication

​vmsgr send (preferred option)

​vmsgr enforce-security

​vlcm launch-app

​Related topics

Package management

vpm commands

vpm list

vpm info

vpm install

vpm uninstall

Lifecycle management

vlcm commands

vlcm list

vlcm terminate-app

App communication

vmsgr send (preferred option)

vmsgr enforce-security

vlcm launch-app

Related topics