Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support
Skip to main content
Vega SDK has a command-line interface (CLI) that lets you build apps and run the Vega Virtual Device (VVD) from the command prompt. 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 and version options

To print the installed Vega CLI version:
The short form is vega -v. Include this version when you report an issue, and use it in a CI pipeline to confirm which CLI the build ran with. To check the SDK versions your project builds against instead, see Manage Your SDK Versions. To explore options for all Vega commands:
To get help for a specific command:
For example, to see all options for vega build command:

​
Exit codes and error output

Vega CLI commands return exit code 0 on success and a non-zero exit code on failure. Error messages are written to stderr.

​
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:

​
vega clean

To remove the artifacts generated in the <projectroot>/build folder:

​
vega project list-templates

To see the available JavaScript and Turbo module templates you can use to create a sample app:
Example output:

​
vega project generate

To create a Vega project, use the vega project generate command with the required parameters. To create a new app:
The following is a breakdown of the different components in the command:
  • vega project generate - Generates a Vega app.
  • --template - Sets the Vega app or Turbo Module template, which you can find from the vega project list-templates command. In the example, it uses the helloWorld template.
  • --name - Sets 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 - Sets 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.
  • --outputDir (optional) - Sets 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:
The following command combines the vega device install-app and vega device launch-app. For the VVD:
For Fire TV:
For example, to run an app called sampleapp on a Mac M-series machine, the command is:

​
Project compatibility commands

The vega project compatibility commands manage the OS version your app supports. They resolve compatible package versions, re-align your project to an OS version target, validate your configuration, and regenerate manifest module entries. For the concepts behind these commands, see Target OS Versions.

​
vega project install

To resolve OS-version-compatible @amazon-devices/* package versions into package.json:
Neither install nor install --fix downloads packages or changes the node_modules folder. Both resolve compatible versions and write them into package.json. The two forms differ in scope:
  • vega project install <packages..> - Adds the named @amazon-devices/* packages to package.json as dependencies, if all compatibility checks pass. This is the only form that adds a new dependency.
  • vega project install --fix - Re-aligns every existing @amazon-devices/* version in package.json to the compatibility profile. It doesn’t add new packages.
All options are optional. When you omit --os-version and --rn-version, the command reads them from your project’s manifest.toml and package.json. Both --fix and --dry-run default to off. --os-min is the one option that writes manifest.toml rather than package.json, and it’s narrower than the other options:
  • It takes effect only together with --fix. Neither a bare vega project install --fix nor an install <package> run writes min.
  • Pass it with --os-version. On a project that has no [os.version] section, install can’t resolve a target, so it fails with Missing OS Version and writes nothing.
  • With both flags on a project that has no [os.version] section, install creates the section, sets min, seeds target, and confirms with 📝 Set [os.version] min = "<v>" in manifest.toml.
  • When [os.version] already exists, this form writes min only and leaves target unchanged. A legacy [os] section counts as an existing section. To change target, use vega project update-manifest.
For example, to re-align every OS-provided package in your project:
Example output:
Running vega project doctor afterward is optional but recommended. install --fix resolves versions, and doctor validates the result and runs the source-level OS version lint. For details, see vega project doctor. With --dry-run, the command previews what it resolves without writing changes, and the header becomes 🔍 Dry run — no changes will be made.

​
vega project update

To re-align your project’s npm packages and manifest to your OS version target:
update re-aligns only the versions of packages your app already depends on. It bumps each one to the version compatible with your OS target and leaves the rest unchanged. To add a new dependency, use vega project install. All options are optional. When you omit them, the command reads --os-version, --os-min, and --rn-version from your project’s manifest.toml, and --dry-run defaults to off. Both update and install --fix re-align existing @amazon-devices/* versions in package.json to the compatibility profile, and both accept --os-version and --os-min. Use install --fix for the normal setup and re-align flow, and for creating an [os.version] section that doesn’t exist yet. Use update when you want a reviewable change plan before anything is written, because --dry-run reports each package version transition. For example, to preview a re-alignment against the target in your manifest.toml:
Example output:
In the plan, the 🔄 icon marks a changed package and the ✓ icon marks an unchanged one. When nothing needs to change, the command reports ✅ All packages are up to date.

​
vega project doctor

To validate your project’s OS version compatibility, including configuration, dependencies, and lint rules:
All options are optional. When you omit them, the command reads the values from your project. Pass them only to override what your project already configures. doctor runs the following checks:
  • The SDK compatibility manifest is present.
  • Your project configuration resolves.
  • [os.version].min and [os.version].target are both valid, minted OS versions.
  • [os.version].min is less than or equal to [os.version].target.
  • Your @amazon-devices/* dependency versions match the SDK profile.
  • The OS version module entries are present in manifest.toml.
  • The source-level OS version lint rule, no-unguarded-os-api, passes.
The no-unguarded-os-api rule flags each reference to an API introduced in an OS version newer than your [os.version].min. A reference passes when it sits inside an isPresentOnOS() guard or carries an // @os-version-ok comment on the line preceding its import. The rule reports the usage site, not the import line. Example output:
Because OS 1.2 is the only minted OS version as of Vega SDK 0.24, min and target are both 1.2. The lint reports No OS version issues because nothing was introduced after min, so there’s nothing to guard. When a later OS version is minted and you set min below target, the lint flags every unguarded reference to an API introduced after your min. It reports each one as file:line:column rule-id with the message indented beneath, the summary becomes ❌ 1 check(s) failed., and doctor exits non-zero. In the results, the ✅ icon marks a passing check, ⚠️ marks a warning, and ❌ marks a failure. vega project doctor exits non-zero when any check with fail severity fails, so you can use it as a gate in your CI pipeline. For more information, see Integrating the Vega SDK into CI Pipelines.

​
vega project update-manifest

To regenerate the OS version module entries in manifest.toml from your [os.version] configuration:
This command writes only the OS version entries, not your @amazon-devices/* package entries, which the build regenerates for you. It writes the following entries:
  • One [[needs.module]] entry for your [os.version].min, in the form /com.amazon.vega.os@IVega_<min>. Your app doesn’t install on a device older than min.
  • One [[wants.module]] entry for each OS version above min and up to [os.version].target, in the form /com.amazon.vega.os@IVega_<v>. When min and target are equal, there are no wants.
When you pass the OS version on the command line, pass both --os-min and --os-version together. min defines which modules are needs and target defines the upper bound for wants, so the pair determines the generated module entries. When you omit both, the command reads them from your manifest.toml. Don’t pass only one. For example, to generate the module entries for a project that targets OS 1.2:
Example output:
With --dry-run, the command prints the generated TOML instead of writing it. For the manifest field definitions, see Manifest [os.version] Section. For more information about needs and wants, see Manifest [needs] Section and Manifest [wants] Section.

​
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:
To see all available device commands:

​
vega device copy-from

To copy device files to the host computer:

​
vega device copy-logs

To retrieve the artifact files from a device:

​
vega device copy-to

To copy host files to the device:

​
vega device get-log-info

To retrieve log information from a device:

​
vega device info

To retrieve device metadata in JSON format, including device type, OS version, hostname, architecture, profile, product name, build description, whether the device is simulated or physical, and Developer Mode status:
Example output:

​
vega device install-app

To install an app on a device or the VVD, 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:
To automatically find the correct .vpkg in the directory and install it:
To specify a debug build type:
To specify a release build type:

​
vega device installed-apps

To list the apps installed on a device:
For example, to see the list of all apps installed on the VVD:

​
vega device installed-packages

To list all packages installed on a device:
For example, to see the list of all packages installed on the VVD:

​
vega device is-app-installed

To check for app installation using app name:
To check for app installation using project directory:

​
vega device is-app-running

To check if an app runs on the device using app name:
To check if an app runs on the device using project directory:

​
vega device is-connected

To check the connection status of a specific device:
Example:
Output when connected:
Output when not connected:

​
vega device launch-app

To launch the app on a device using app name:
To launch the app on a device using project directory:

​
vega device list

To list connected devices (Fire TV Stick and VVD):
The VVD appears as: VirtualDevice : tv - architecture - OS type - hostname Example output with a connected Fire TV Stick (GXXXXXXXXXXXXXXX) and a running VVD:

​
vega device reboot

To reboot the given device:

​
vega device run-cmd

To run a command on a specific device:

​
vega device running-apps

To list all apps running on a device:
For example, to see the list of all apps running on the VVD:

​
vega device shell

To start a shell session on a device:

​
vega device start-log-stream

To start streaming logs from a device:

​
vega device stop-log-stream

To stop streaming logs from a device:

​
vega device start-port-forwarding

To start or reverse port forwarding for a device:

​
vega device stop-port-forwarding

To stop or reverse port forwarding for a device:

​
vega device terminate-app

To terminate an app on a device using app name:
To terminate an app on a device using project directory:
Example:

​
vega device uninstall-app

To uninstall an app from a device using app name:
To uninstall an app on a device using project directory:
Example:

​
Vega Virtual Device commands

​
vega virtual-device status

To find the status of the VVD:

​
vega virtual-device start

To start the VVD:
The terminal displays this message:

​
vega virtual-device stop

To stop the VVD:
Last modified on August 19, 2026