Vega SDK CLI Reference
Vega SDK has a command-line interface (CLI) functions that let you build apps and run the virtual device in your terminal. When running commands, replace all placeholders with actual values to prevent errors. For example, replace <APPNAME> and <COMPANY NAME.APPNAME> with your app and company name. Don't use amazon as your company name or package ID.
This page describes the Vega CLI commands and examples.
Help option
To explore options for all Vega commands, use:
kepler --help
To get all information about a specific command, use:
--help
For example, to see all options for kepler build command, use:
kepler build --help
Commonly used commands
npm run build:app
Use the npm run build:app command to compile the native portion of your app and produce the vpkg. The command takes the following arguments:
-t,--target,--targets- Specifies where to build the app. You can use these targets:tv,4kmax_g1_vega,sim_tv_x86_64, andsim_tv_aarch64.-b,--build-type,--build-types- Specifies the mode to build the app. Available types:DebugandRelease. Defaults toReleaseif not specified.
To build an app, use:
npm install
npm run build:app
kepler clean
To remove the artifacts generated in the <projectroot>/build folder, use:
kepler clean
kepler project list-templates
To see the available JavaScript and Turbo module templates you can use to create a sample app, run:
kepler project list-templates
Example output:
kepler project list-templates
Available templates:
idl-turbo-module: A Turbo Module that's compatible with all supported React Native versions and uses native IDL APIs
hello-world: A Vega app that depends on React Native v0.72
basic-turbo-module: A Turbo Module that's compatible with all supported React Native versions
kepler project generate
To create a Vega project, use:
kepler project generate
To create a new app, use:
kepler project generate --template hello-world --name `<APPNAME>` --packageId `com.<COMPANY NAME>.<APPNAME>` --outputDir `<APPNAME>`
The following is a breakdown of the different components in the command:
-
kepler project generate- Use this command to generate a Vega app. -
--template- The name of the Vega app or Turbo Module template, which you can find from thekepler project list-templatescommand. In the example, it uses thehello-worldtemplate. -
--name- The name of your new app or Turbo Module. The name can't contain whitespace or special characters. Replace<APPNAME>with the desired name for your new app. -
--packageId- The package ID for manifest.toml required in React Native for Vega apps, not in Turbo Module. Replace<COMPANY NAME>with the name of your company and<APPNAME>with the name of your app. This sets the package ID for the new app. -
--outputDir (optional)- Specifies the output directory for new app files. Replace<APPNAME>with the actual name of your app.
When you follow this format, the command shows the path to your new project.
kepler run-kepler
To install and run your app, use:
run-kepler
The following command combines the kepler device install-app and kepler device launch-app.
For the VVD:
kepler run-kepler <Vpkg path> <App ID> -d VirtualDevice
For Fire TV:
kepler run-kepler <Vpkg path> <App ID> -d <DSN>
For example, to run an app called keplersampleapp on a Mac M-series machine, the command is:
kepler run-kepler build/x86_64-release/keplersampleapp_aarch64.vpkg com.amazondeveloper.keplersampleapp.main -d VirtualDevice
Device commands
The Vega CLI device command interface provides a way for you to interact with physical devices and the VVD. You must install and make VDA available on the path for device commands to work.
The general command format is:
kepler device <command> [parameters]
kepler device copy-from
To copy device files to the host computer, use:
kepler device copy-from --device <device name> --source <file or directory> --destination <file or directory>
kepler device copy-logs
To retrieve the artifact files from a device, use:
kepler device copy-logs --device <device name> --artifact <artifact name> --directory <directory for files>
kepler device copy-to
To copy host files to the device, use:
kepler device copy-to --device <device name> --source <file or directory> --destination <file or directory>
kepler device get-log-info
To retrieve the Vega log information (list of artifacts and files) from a device, use:
kepler device get-log-info --device <device name>
kepler device copy-logs-info
To pull log files from the device, use:
kepler device copy-log-info --device <device name>
kepler device install
To install an app on a device and simulator, add arguments for the path (-p) to your app's package. The path follows this syntax: build/<ARCH>-<BUILD_TYPE>/<APP_NAME>_<ARCH>.vpkg.
For example, if keplersampleapp runs on a Mac x86 machine, use:
kepler device install-app -p build/x86_64-release/keplersampleapp_x86_64.vpkg --device <device name>
To automatically find the correct .vpkg in the directory and install it, use:
kepler device install-app --dir .
To specify a debug build type, use:
kepler device install-app --dir . -b Debug
To specify a release build type, use:
kepler device install-app --dir . -b Release
kepler device installed-apps
To list the apps installed on a device:
kepler device installed-apps --device <device name>
For example, to see the list of all apps installed on the simulator, use:
kepler device installed-apps --device VirtualDevice
kepler device installed-packages
To list all packages installed on a device:
kepler device installed-packages --device <device name>
For example, to see the list of all packages installed on the simulator, use:
kepler device installed-packages --device VirtualDevice
kepler device is-app-installed
To check for app installation on the device, use:
kepler device is-app-installed --device <device name> --appName <app name> --directory <project directory>
--appName if you specify --directory, or delete --directory if you specify --appName.kepler device is-app-running
To check if the given app runs on the device, use:
kepler device is-app-running --device <device name> --appName <app name> --directory <project directory>
--appName if you specify --directory, or delete --directory if you specify --appName.kepler device is-connected
To check the connection status of a specific device, use:
kepler device is-connected --device <device name>
Example:
kepler device is-connected --device GXX2A1234567890A
When device GXX2A1234567890A connects, the terminal shows:
Device GXX2A1234567890A is connected
If the device fails to connect, the terminal shows:
Device GXX2A1234567890A is not connected
kepler device launch-app
To launch the app on a device, use:
kepler device launch-app --device <device name> --appName <app name> --directory <project directory>
--appName if you specifiy --directory, or delete --directory if you specify --appName.The app name follows this syntax: com.<COMPANY NAME>.<APP_NAME>.main. For keplersampleapp, use:
kepler device launch-app -a com.<COMPANY NAME>.keplersampleapp.main
kepler device list
To list connected devices (Fire TV Stick and Vega Virtual Device), use:
kepler device list
The Vega Virtual Device appears as: VirtualDevice : tv - architecture - OS type - hostname
Example output with a connected Fire TV Stick (GXX2A1234567890A) and running virtual device:
GXX2A1234567890A : A1ZZ32RVTQ796E
VirtualDevice : tv - x86_64 - OS - amazon-ab123456cd789012
kepler device reboot
To reboot the given device, use:
kepler device reboot --device <device name>
kepler device run-cmd
To run a command on a specific device, use:
kepler device run-cmd --device <device name> --command '<command to run>'
kepler device running-apps
To list all apps running on a device, use:
kepler device running-apps --device <device name>
For example, to see the list of all apps running on the simulator, use:
kepler device running-apps --device VirtualDevice
kepler device shell
To start a shell session on a device, use:
kepler device shell --device <device name>
kepler device start-log-stream
To start streaming logs from a device, use:
kepler device start-log-stream --device <device name>
kepler device stop-log-stream
To stop streaming logs from a device, use:
kepler device stop-log-stream --device <device name>
kepler device start-port-forwarding
To start or reverse port forwarding for a device, use:
kepler device start-port-forwarding --device <device name> --port <port number> --forward <true|false>
kepler device stop-port-forwarding
To stop or reverse port forwarding for a device, use:
kepler device stop-port-forwarding --device <device name> --port <port number> --forward <true|false>
kepler device terminate-app
To terminate an app on a device, use:
kepler device terminate-app --device <device name> --appName <app name> --directory <project directory>
--appName if you specify --directory, or delete --directory if you specify --appName.Example:
kepler device terminate-app --appName com.amazondeveloper.keplersampleapp.main --device VirtualDevice
// Output
Force stopping pkg: com.amazondeveloper.keplersampleapp
kepler device uninstall-app
To uninstall an app from a device, use:
kepler device uninstall-app --device <device name> --appName <app name> --directory <project directory>
Example:
kepler device uninstall-app --appName com.amazondeveloper.keplersampleapp.main --device VirtualDevice
// Output
Uninstalling 'com.amazondeveloper.keplersampleapp' ...success
Vega Virtual Device commands
kepler virtual-device status
To find the status of the virtual device, use:
kepler virtual-device status
kepler virtual-device start
To start the simulator, use:
kepler virtual-device start
The terminal displays this message:
Launching default instance.
Waiting for virtual device to boot.
Launch process complete.
Virtual device shell available.
Virtual device ready.
kepler virtual-device stop
To stop the simulator, use:
kepler virtual-device stop
Related topics
Last updated: Sep 30, 2025
