App Management and Communication Tools

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

Copy code Copied to clipboard.

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

Copy code Copied to clipboard.

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: vpm list (packages | components) [--category=<category>]... [--uri=<uri>]... )

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: vpm info <id> [--package]

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 then run vpm install. The file must be in .vpkg format and must exist on the device before using vpm install. Package install over the network isn’t supported.

Command: vpm install <path-to-package> [--force]

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: vpm uninstall <package-id>

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.

Copy code Copied to clipboard.

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.

Copy code Copied to clipboard.

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, this option is limited to app launch only.

Command: vlcm launch-app <uri>

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

Related topics

• Vega SDK CLI Reference
• Vega Studio Performance CLI
• Vega Studio Commands
• Use VPT for Vega App Packages

Last updated: Sep 30, 2025