Vega SDK CLI Reference
Vega SDK has a command-line interface (CLI) that lets 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>, <COMPANY NAME.APPNAME>, and <projectroot> with your app name, company name, and project directory path. 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:
vega --help
To get help for a specific command:
vega <command> --help
For example, to see all options for vega build command:
vega build --help
Commonly used commands
npx react-native build-vega
Use the npx react-native build-vega command to compile your app and produce the vpkg.
To build an app:
npm install
npx react-native build-vega
vega clean
To remove the artifacts generated in the <projectroot>/build folder:
vega clean
vega project list-templates
To see the available JavaScript and Turbo module templates you can use to create a sample app:
vega project list-templates
Example output:
vega 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
vega project generate
To create a Vega project, use the vega project generate command with the required parameters.
To create a new app:
vega 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:
-
vega 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 thevega 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.
vega run-app
To install and run your app:
vega run-app <Vpkg path> <App ID> -d <device>
The following command combines the vega device install-app and vega device launch-app.
For the VVD:
vega run-app <Vpkg path> <App ID> -d VirtualDevice
For Fire TV:
vega run-app <Vpkg path> <App ID> -d <DSN>
For example, to run an app called sampleapp on a Mac M-series machine, the command is:
vega run-app build/x86_64-release/sampleapp_aarch64.vpkg com.amazondeveloper.sampleapp.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:
vega device <command> [parameters]
To see all available device commands:
vega device --help
vega device copy-from
To copy device files to the host computer:
vega device copy-from --device <device name> --source <file or directory> --destination <file or directory>
vega device copy-logs
To retrieve the artifact files from a device:
vega device copy-logs --device <device name> --artifact <artifact name> --directory <directory for files>
vega device copy-to
To copy host files to the device:
vega device copy-to --device <device name> --source <file or directory> --destination <file or directory>
vega device get-log-info
To retrieve log information from a device:
vega device get-log-info --device <device name>
vega 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 sampleapp runs on a Mac x86 machine:
vega device install-app -p build/x86_64-release/sampleapp_x86_64.vpkg --device <device name>
To automatically find the correct .vpkg in the directory and install it:
vega device install-app --dir .
To specify a debug build type:
vega device install-app --dir . -b Debug
To specify a release build type:
vega device install-app --dir . -b Release
vega device installed-apps
To list the apps installed on a device:
vega device installed-apps --device <device name>
For example, to see the list of all apps installed on the virtual device:
vega device installed-apps --device VirtualDevice
vega device installed-packages
To list all packages installed on a device:
vega device installed-packages --device <device name>
For example, to see the list of all packages installed on the virtual device:
vega device installed-packages --device VirtualDevice
vega device is-app-installed
To check for app installation using app name:
vega device is-app-installed --device <device name> --appName <app name>
To check for app installation using project directory:
vega device is-app-installed --device <device name> --directory <project directory>
vega device is-app-running
To check if an app runs on the device using app name:
vega device is-app-running --device <device name> --appName <app name>
To check if an app runs on the device using project directory:
vega device is-app-running --device <device name> --directory <project directory>
vega device is-connected
To check the connection status of a specific device:
vega device is-connected --device <device name>
Example:
vega device is-connected --device GXX2A1234567890A
Output when connected:
Device GXX2A1234567890A is connected
Output when not connected:
Device GXX2A1234567890A is not connected
vega device launch-app
To launch the app on a device using app name:
vega device launch-app --device <device name> --appName <app name>
To launch the app on a device using project directory:
vega device launch-app --device <device name> --directory <project directory>
vega device list
To list connected devices (Fire TV Stick and Vega Virtual Device):
vega 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
vega device reboot
To reboot the given device:
vega device reboot --device <device name>
vega device run-cmd
To run a command on a specific device:
vega device run-cmd --device <device name> --command '<command to run>'
vega device running-apps
To list all apps running on a device:
vega device running-apps --device <device name>
For example, to see the list of all apps running on virtual device:
vega device running-apps --device VirtualDevice
vega device shell
To start a shell session on a device:
vega device shell --device <device name>
vega device start-log-stream
To start streaming logs from a device:
vega device start-log-stream --device <device name>
vega device stop-log-stream
To stop streaming logs from a device:
vega device stop-log-stream --device <device name>
vega device start-port-forwarding
To start or reverse port forwarding for a device:
vega device start-port-forwarding --device <device name> --port <port number> --forward <true|false>
vega device stop-port-forwarding
To stop or reverse port forwarding for a device:
vega device stop-port-forwarding --device <device name> --port <port number> --forward <true|false>
vega device terminate-app
To terminate an app on a device using app name:
vega device terminate-app --device <device name> --appName <app name>
To terminate an app on a device using project directory:
vega device terminate-app --device <device name> --directory <project directory>
Example:
vega device terminate-app --appName com.amazondeveloper.sampleapp.main --device VirtualDevice
// Output
Force stopping pkg: com.amazondeveloper.sampleapp
vega device uninstall-app
To uninstall an app from a device using app name:
vega device uninstall-app --device <device name> --appName <app name>
To uninstall an app on a device using project directory:
vega device uninstall-app --device <device name> --appName <app name> --directory <project directory>
Example:
vega device uninstall-app --appName com.amazondeveloper.sampleapp.main --device VirtualDevice
// Output
Uninstalling 'com.amazondeveloper.sampleapp' ...success
Vega Virtual Device commands
vega virtual-device status
To find the status of the virtual device:
vega virtual-device status
vega virtual-device start
To start the simulator:
vega 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.
vega virtual-device stop
To stop the simulator:
vega virtual-device stop
Related topics
Last updated: Dec 22, 2025
