Manage Your SDK Versions

The Vega SDK Manager is accessible through the Vega CLI (a command-line binary called vega). The tool simplifies how you manage SDK versions for your development projects. You can install, switch between versions, and integrate with CI/CD pipelines seamlessly. It works like nvm for Node.js or pyenv for Python.

Prerequisites

Verify you have the Vega CLI before proceeding.

If you have the latest Vega SDK (version 0.22+): The Vega CLI is already available. Proceed to get started or common workflows.

If you have an older Vega SDK version: Upgrade to the latest version by following the Vega SDK installation instruction.

Get started

Follow these steps to verify your installation and create your first project configuration.

1. Check if you have the SDK Manager:

   Copy code Copied to clipboard.

   vega --version
   

   If you get a "command not found" error, follow the Prerequisites to install or upgrade your Vega SDK.

2. Install the Vega SDK (if needed):

   To install the latest SDK version

   Copy code Copied to clipboard.

   vega sdk install
   

   Vega Virtual Device installation:

   Vega SDK installs the Vega Virtual Device (VVD) by default. The VVD provides a virtual environment for testing and running your Vega app. For example, in a CI/CD environment, you don't need the virtual device.

   If you would like to skip the virtual device installation, use the environment variable SKIP_VVD_INSTALL=true before running the install command:

   Copy code Copied to clipboard.

   export SKIP_VVD_INSTALL=true
   vega sdk install
   

   To install a specific version

   Copy code Copied to clipboard.

   vega sdk install 1.2.3
   

   To see available versions

   Copy code Copied to clipboard.

   vega sdk list-remote
   

3. Verify your installation:

   Copy code Copied to clipboard.

   vega sdk list-installed
   

4. Create a vega-sdk-requirements.json file in your project root:

   Copy code Copied to clipboard.

   {
      "vegaSdkVersion": "1.2.3"
   }
   

Common workflows

These examples show how to use the SDK Manager in your development workflow.

Set up a new project

Follow this workflow to configure your development environment for a new Vega project.

1. Verify Vega CLI is installed:

   Copy code Copied to clipboard.

   vega --version
   

2. Install the SDK:

   Copy code Copied to clipboard.

   vega sdk install
   

3. Verify installation:

   Copy code Copied to clipboard.

   vega sdk list-installed
   

4. Run health checks:

   Copy code Copied to clipboard.

   vega sdk config doctor
   

   This verifies your SDK installation, checks environment configuration, and identifies potential issues.

5. Create project requirements file (recommended):

   Copy code Copied to clipboard.

   echo '{"vegaSdkVersion": "1.2.3"}' > vega-sdk-requirements.json
   

How requirements files work

When you run any Vega command in a directory containing vega-sdk-requirements.json, Vega:

1. Looks for the vegaSdkVersion field in the file.
2. Uses vegaSdkVersion for all SDK operations in that project.
3. Overrides any global default version settings.

Example project structure

Here's how a typical project with version requirements looks:

my-project/
├── vega-sdk-requirements.json
├── src/
└── README.md

The vega-sdk-requirements.json file contains:

{
  "vegaSdkVersion": "1.2.3"
}

Manage multiple projects

Each project can have its own SDK version by using vega-sdk-requirements.json:

# Project A uses SDK 1.2.3
cd project-a
cat vega-sdk-requirements.json  # {"vegaSdkVersion": "1.2.3"}
vega sdk list-installed  # Shows 1.2.3 as active
vega build

# Project B uses SDK 2.0.0
cd ../project-b
cat vega-sdk-requirements.json  # {"vegaSdkVersion": "2.0.0"}
vega sdk list-installed  # Shows 2.0.0 as active
vega build

Update SDK version

Keep your projects current with the latest SDK features and bug fixes.

Quick update

1. Check available versions:

   Copy code Copied to clipboard.

   vega sdk list-remote
   

2. Install new version:

   Copy code Copied to clipboard.

   vega sdk install 2.0.0
   

3. Set as default (optional):

   Copy code Copied to clipboard.

   vega sdk use 2.0.0
   

4. (Optional) Clean up old versions:

   Copy code Copied to clipboard.

   vega sdk uninstall 1.2.3
   

Safe update (test before committing)

Test new SDK versions in a separate branch before merging:

# Install new version alongside existing
vega sdk install 2.0.0

# Test in a separate branch
git checkout -b test-sdk-2.0.0
echo '{"vegaSdkVersion": "2.0.0"}' > vega-sdk-requirements.json
vega build

# If successful, merge and update team
git checkout main
git merge test-sdk-2.0.0

Link existing SDK installation

If you already have a Vega SDK installed outside the SDK Manager, you can link it instead of reinstalling.

# Auto-discover from KEPLER_SDK_PATH
vega sdk link --discover

# Or link from specific path
vega sdk link --path /path/to/existing/sdk

# Verify the link
vega sdk list-installed

CI/CD integration

For automated environments like CI/CD pipelines, Vega provides two methods to enable non-interactive mode, preventing any prompts or interactive behavior that would block automation.

Non-interactive mode for automation

Method 1: CLI flag (recommended for individual commands)

Use the --non-interactive flag on commands that support it:

# Install SDK without any prompts
vega sdk install --non-interactive

# Setup configuration non-interactively
vega sdk config setup --non-interactive --sdk-path /opt/vega-sdk

# Link SDK without prompts
vega sdk link --discover --non-interactive

Method 2: Environment variable (recommended for entire pipeline)

Set the NONINTERACTIVE environment variable to true:

# Set environment variable for the entire session
export NONINTERACTIVE=true

# Now all commands run non-interactively
vega sdk install
vega sdk config setup
vega sdk link --discover

Precedence rules

When both methods are used, the CLI flag takes precedence:

1. CLI flag (--non-interactive) - Highest priority.
2. Environment variable (NONINTERACTIVE=true) - Lower priority.

This allows you to set a default behavior with the environment variable while still able to override it with the CLI flag if needed.

Advanced features

These advanced configuration options provide additional flexibility for specialized development environments and workflows.

Custom configuration file location

By default, Vega stores its configuration in ~/vega/config.json. You can customize this location using the VEGA_CONFIG_FILE environment variable. This is useful for:

• Running multiple Vega configurations on the same machine
• Using a shared configuration file across a team
• CI/CD environments where the default path isn't suitable
• Testing different configurations without affecting your main setup

Set custom configuration path

# Set custom configuration file location
export VEGA_CONFIG_FILE="/path/to/custom/config.json"
  		  
# Then run setup or any other command
vega sdk config setup
  		  
# Or combine in a single command
export VEGA_CONFIG_FILE="/path/to/custom/config.json" && vega sdk config setup

Make the custom configuration path persistent

To use a custom configuration location permanently, add the export to your shell profile:

# For bash (~/.bashrc or ~/.bash_profile)
echo 'export VEGA_CONFIG_FILE="/path/to/custom/config.json"' >> ~/.bashrc
  		  
# For zsh (~/.zshrc)
echo 'export VEGA_CONFIG_FILE="/path/to/custom/config.json"' >> ~/.zshrc

CI/CD example

# Set custom configuration for CI/CD pipeline
export VEGA_CONFIG_FILE="/opt/ci/config.json"
export NONINTERACTIVE=true
  		  
# Setup and install
vega sdk config setup --sdk-path /opt/vega-sdk
vega sdk install

Best practices

These practices help you avoid common issues and maintain a stable development environment with the SDK Manager.

1. Always use requirements files.

   Commit vega-sdk-requirements.json to version control for consistent SDK versions across your team.

2. Pin-specific versions.

   Avoid breaking changes and ensure reproducible builds by using exact version numbers.

   // Specific version
   {"vegaSdkVersion": "1.2.3"}
   

3. Keep SDK Manager updated.

   New SDK Manager versions include improvements, bug fixes, and support for newer SDK versions.

   Copy code Copied to clipboard.

   vega update
   

4. Use non-interactive mode in CI/CD.

   CI/CD pipelines can't respond to prompts or confirmations. Without non-interactive mode, your builds may hang indefinitely waiting for user input that may not come.

   # Set environment variable for entire pipeline
   export NONINTERACTIVE=true
   export SKIP_VVD_INSTALL=true
   
   # Use flag for specific commands
   vega sdk install --non-interactive 
   

Command reference

This section lists all SDK Manager commands with their descriptions. Use this as a quick lookup when you need specific command syntax.

Basic commands

CI/CD commands

Help

Global options

Troubleshooting

If you encounter any issues, see Troubleshooting SDK Manager Issues.

Related topics

• Install the Vega SDK
• Vega SDK Install Issues

Last updated: Dec 22, 2025