Use VPT for Vega App Packages

VPT manages Vega app packages. Use it to create, examine, manage, and validate .vpkg files (Vega’s standard package format). To get started with VPT, install the Vega Software Development Kit (SDK), which includes two main command-line tools:

VPT - Manages package operations like creation and validation
Vega CLI - Handles the overall app development workflow, including building and deploying apps

While Vega CLI uses VPT during app builds, you can also run VPT directly to:

Examine packages
Validate content
Add custom signatures to your apps

Commands

VPT provides the following command categories. For a complete list of commands and their latest options, use vpt help.

Package information

These commands view package details and contents.

info

Shows package information, including ID, title, and build details.

Usage: vpt info [OPTIONS] <PACKAGE>

Arguments:
<PACKAGE>          Path to the vpkg

Options:
  --json           Output in JSON format
  -h, --help       Print help

Example:

vpt info /path/to/keplersampleapp.vpkg

// Output
Sample App    com.amazondeveloper.keplersampleapp v1.3.4 b53

show-contents

Lists all files in the package.

Usage: vpt show-contents [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>     Path to the vpkg

Options:
  -h, --help    Print help

Example:

vpt show-contents /path/to/keplersampleapp.vpkg

// Output
Package contents:
assets/ (6 files)
lib/ (2 files)
manifest.toml
meta-info/ (4 files)

Package creation and extraction

These commands create and modify packages.

pack

Creates a package from source directories. You can specify package name, version, and build number.

Usage: vpt pack [OPTIONS] <SOURCE_PATHS>...

Arguments:
  <SOURCE_PATHS>...  Source directories

Options:
  -n, --pkg-name <PKG_NAME>          Name of the package
  -d, --dest-path <DEST_PATH>        Destination path
  -b, --build-number <BUILD_NUMBER>  Build number
  -v, --version <VERSION>            Build version
      --validate                     Enforce validation of the manifest
  -h, --help                         Print help

Example:

vpt pack /path/to/source --pkg-name keplersampleapp --dest-path /path/to/output --version 1.0.0 --build-number 42

// Output
Creating package keplersampleapp...
Validating manifest...
Package created at /path/to/output/keplersampleapp.vpkg

unpack

Extracts all package files to a destination path.

Usage: vpt unpack [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>                    Path to the vpkg

Options:
  -d, --dest-path <DEST_PATH>  Destination path
  -h, --help                   Print help

Example:

vpt unpack /path/to/keplersampleapp.vpkg --dest-path /path/to/output

// Output
Extracting package contents...
Files extracted to /path/to/output

dump

Extracts a file from the package. Prints to stdout, or saves to the destination path you specified.

Usage: vpt dump [OPTIONS] <PACKAGE> <ENTRY>

Arguments:
  <PACKAGE>                    Path to the vpkg
  <ENTRY>                      Path to the entry inside vpkg

Options:
  -d, --dest-path <DEST_PATH>  Destination path
  -h, --help                   Print help

Example:

vpt dump /path/to/keplersampleapp.vpkg manifest.toml

// Output
Extracting manifest.toml from keplersampleapp.vpkg
Content written to stdout

extract-locales

Extracts localization files from a package as JSON or text.

Usage: vpt extract-locales [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>                           Path to the vpkg

Options:
  -f, --format <FORMAT>               Output format [default: json] [possible values: json, text]
  -h, --help                          Print help

Example:

vpt extract-locales --format json /path/to/keplersampleapp.vpkg

// Output
Extracting localization files...
Files extracted to current directory:
- en/strings.json
- es/strings.json

Package signature and verification

These commands handle security and validation.

pull

Extracts digest and signature files from the package. A digest file lists cryptographic checksums for all files in the VPKG, while a signature file contains a detached cryptographic signature that verifies the digest file’s authenticity. Use --json-digest to extract the digest file in JSON format, or --json-signature to extract the signature file in JSON format.

Usage: vpt pull [OPTIONS] <--signature|--digest|--json-signature|--json-digest> <PACKAGE> <DEST>

Arguments:
  <PACKAGE>           Path to the vpkg
  <DEST>              Destination path

Options:
  --signature
  --digest
  --json-signature
  --json-digest
  -h, --help          Print help

Example:

vpt pull --signature /path/to/keplersampleapp.vpkg /path/to/output/digest.sig

// Output
Extracting signature from keplersampleapp.vpkg
Signature saved to /path/to/output/digest.sig

push

Adds a signature file to the package. Use --json-signature to insert a JSON-formatted signature file that corresponds to the package’s digest.

Usage: vpt push [OPTIONS] <--signature <SIGNATURE>|--json-signature <JSON_SIGNATURE>> <PACKAGE>

Arguments:
  <PACKAGE>                           Path to the vpkg

Options:
  --signature <SIGNATURE>             Legacy signature of a digest file path to push
  --json-signature <JSON_SIGNATURE>   Signature of a digest.json file path to push
  -h, --help                          Print help

Example:

vpt push --signature /path/to/input/digest.sig /path/to/keplersampleapp.vpkg

// Output
Adding signature to keplersampleapp.vpkg
Signature successfully added

sign

Signs a message using a private key and certificate.

Usage: vpt sign [OPTIONS] <MESSAGE> <PRIVKEY> <CERTFILE> <OUTPUTFILE>

Arguments:
  <MESSAGE>      Message to sign
  <PRIVKEY>      Private key used to sign the message
  <CERTFILE>     X.509 certificate that corresponds to the private key
  <OUTPUTFILE>   Output path

Options:
  -r, --resign   Resign a signed message
  -h, --help     Print help

Example:

vpt sign --resign /path/to/input/digest.sig /path/to/developer-private.key /path/to/developer-cert.pem /path/to/output/digest.sig

// Output
Signing digest.sig with provided key and certificate
Signature created at /path/to/output/digest.sig

verify

Verifies a message’s signature using specified certificates.

Usage: vpt verify [OPTIONS] <MESSAGEFILE> <SIGFILE> <CERTIFICATES>...

Arguments:
  <MESSAGEFILE>      File to verify
  <SIGFILE>          Signature used to verify the message
  <CERTIFICATES>...  List of X.509 certificates to verify against

Options:
  -p, --partial      Perform a partial/non-exhaustive verification using only the provided CAs
  -h, --help         Print help

Example:

vpt verify /path/to/message.txt /path/to/message.sig /path/to/cert.pem

// Output
Verifying signature...
Signature verification successful

checksum

Calculates the package checksum.

Usage: vpt checksum [OPTIONS] <PACKAGE>

Arguments:
  <PACKAGE>     Path to the vpkg

Options:
  -h, --help    Print help

Example:

vpt checksum /path/to/keplersampleapp.vpkg

// Output
Calculating checksum...
SHA256: a1b2c3d4e5f6...

generate-csr

Creates a certificate signing request (CSR) from a configuration file.

Usage: vpt generate-csr [OPTIONS]

Options:
  -k, --key <KEY>        Private key
  -c, --config <CONFIG>  Config file
  -o, --out <OUT>        Output directory
  -v, --verbose          Print the generated CSR path
  -h, --help             Print help

Example:

vpt generate-csr -k /path/to/private.key -c /path/to/config.json -o /path/to/output/dir -v

// Output
Reading configuration from config.json
Generating CSR using private.key
CSR created at /output/dir/certificate.csr

Package analysis

These commands validate package structure and contents.

validate

Checks if your package manifest meets AppStore requirements. For information about the rules, see the manifest user guide.

Usage: vpt validate [OPTIONS] <PATH>

Arguments:
  <PATH>        Path to the vpkg, directory, or manifest.toml

Options:
  --no-color    Disable colored output
  -h, --help    Print help

Example:

vpt validate keplersampleapp.vpkg

// Output
validating 'keplersampleapp.vpkg' ...
analyzing manifest.toml ...
found issues in manifest.toml ...
manifest validation found 2 errors
manifest.toml:3:1 info: [package.icon] Icon isn't defined in the manifest. Using system default.
  help: Define an icon to help users recognize your app
manifest.toml:15:6 error: [components.interactive.id] Component ID 'com.company.sample.badcomponentname' doesnt have package ID prefix 'com.amazondeveloper.keplersampleapp'
  help: Component ID should follow the format: package_id.component_name
manifest.toml:9:1 error: [components.interactive.categories] No interactive component declares 'com.amazon.category.main' category. App can't launch without package-id or package ASIN.
  help: One interactive component should declare 'com.amazon.category.main' category in the manifest

Create a custom signature for your package

Pull the signature file from the package:

vpt pull --json-signature /path/to/keplersampleapp.vpkg /path/to/pulled/digest.json.sig

// Output
Extracting signature from keplersampleapp.vpkg
Signature saved to /path/to/pulled/digest.json.sig

Sign the pulled digest.json.sig file using your private key and certificate:

vpt sign --resign /path/to/pulled/digest.json.sig /path/to/developer-private.key /path/to/developer-cert.pem /path/to/signed/digest.json.sig

// Output
Signing digest.json.sig with provided key and certificate
Signature created at /path/to/signed/digest.json.sig

Push the signed signature file back to the package:

vpt push --json-signature /path/to/signed/digest.json.sig /path/to/keplersampleapp.vpkg

// Output
Adding signature to keplersampleapp.vpkg
Signature successfully added

​Commands

​Package information

​info

​show-contents

​Package creation and extraction

​pack

​unpack

​dump

​extract-locales

​Package signature and verification

​pull

​push

​sign

​verify

​checksum

​generate-csr

​Package analysis

​validate

​Create a custom signature for your package

​Related topics

Commands

Package information

info

show-contents

Package creation and extraction

pack

unpack

dump

extract-locales

Package signature and verification

pull

push

sign

verify

checksum

generate-csr

Package analysis

validate

Create a custom signature for your package

Related topics