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
Native
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>, com.<COMPANY NAME>.<APPNAME>, and <projectroot> with your app name, package ID, 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 the vega build command:

​
Setup commands

​
vega setup-studio

Use vega setup-studio to install the Vega Studio extension when you skipped it during SDK installation, or to reinstall it. This command isn’t currently listed in vega --help, so this reference is the place to find it.
The kepler setup-studio form is equivalent. To install Vega Studio after skipping it during SDK installation:
If the installation fails without a clear error, rerun it with verbose diagnostics:

​
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

The following commands cover building, cleaning, creating, and running your app.

​
npx react-native build-vega

Use the npx react-native build-vega command to compile your app and produce the .vpkg file. 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 in manifest.toml. Required for React Native for Vega apps, not Turbo Modules. 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:
-d is the short form of --deviceId. The vega device commands use --device for the same value. The vega run-app command combines the vega device install-app and vega device launch-app commands. The App ID is optional. If you omit it, the command installs the app but doesn’t launch it. 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 set the [os.version] values in your manifest. For the concepts behind these commands, see Target OS Versions. For the React Native, OS, and host machine combinations that each SDK version supports, see the version compatibility matrix.

​
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 manifest 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 --fix, --os-min, and --os-version on a project that has no [os.version] section, install creates the section, sets min and 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 and --os-min from your project’s manifest.toml and --rn-version from package.json, and --dry-run defaults to off. Both update and install --fix re-align existing @amazon-devices/* versions in package.json to the compatibility manifest 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 compatibility manifest profile.
  • The source-level OS version lint rules pass: no-unguarded-os-api, no-removed-api, and warn-deprecated-api.
The no-unguarded-os-api rule reports an error for 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. The no-removed-api rule reports an error for a reference to an API removed at or before min. The warn-deprecated-api rule reports a warning for a reference to an API deprecated at or before [os.version].target. Example output:
In this example, min is 1.2 and target is 2.0. The lint reports No OS version issues because every API introduced after min is guarded. If your code references an API introduced after min without a guard, the lint flags every such reference. 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 set the [os.version] values in manifest.toml:
This command writes only the [os.version] section, meaning the min and target values. It doesn’t write module entries. The build generates the OS version module entries (/com.amazon.vega.os@IVega_<v>) from [os.version]. It writes them into the validation, staged, and packaged manifests, along with your @amazon-devices/* package entries. On every run, the command also removes tool-owned module entries from your source manifest.toml. These include OS version module entries in the reserved /com.amazon.vega.os@IVega_* family. They also include versioned @amzn/<pkg>@<version> and @amazon-devices/<pkg>@<version> module IDs. Module entries you declare for other system modules are preserved. On a project created with an earlier SDK, the first run deletes these lines from your source-controlled manifest. This diff is expected. Commit it, and don’t restore the entries by hand. When you pass the OS version on the command line, pass both --os-min and --os-version together. When you omit both, the command reads them from your manifest.toml. For example, to add an [os.version] section for a project that targets and requires OS 2.0, which is the recommended setting for SDK 2.0:
The command reports the min and target versions it wrote, and lists any tool-owned module entries it removed from your manifest.
To also support OS 1.2, pass --os-min 1.2. For help choosing, see Choose min. If the command removes tool-owned entries, it also reports 🧹 Removed tool-owned [[needs.module]]/[[wants.module]] entries from manifest.toml. With --dry-run, it reports what it would write and remove, and changes nothing. For the manifest field definitions and how the build generates the module entries, 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. For device commands to work, install the Vega Device Adapter (VDA) and add it to your path. 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:
The --artifact value uses the form artifact/provider, for example system/var_log. The --dir value is the directory on the host computer to copy the files to.

​
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:
The metadata includes the device type, OS version, hostname, architecture, profile, product name, and build description. It also shows whether the device is simulated and whether Developer Mode is on. Example output:

​
vega device install-app

To install an app on a device or the VVD, pass the .vpkg path with -p. The path follows this syntax: build/<ARCH>-<BUILD_TYPE>/<APP_NAME>_<ARCH>.vpkg. For example, to install sampleapp 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 the app name:
To check for app installation using the project directory:

​
vega device is-app-running

To check if an app is running on the device using the app name:
To check if an app is running on the device using the 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 the app name:
To launch the app on a device using the project directory:

​
vega device list

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

​
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 forward or reverse port forwarding for a device:

​
vega device stop-port-forwarding

To stop forward or reverse port forwarding for a device:

​
vega device terminate-app

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

​
vega device uninstall-app

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

​
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 October 29, 2026