Install vpctl

Install the vpctl command-line tool, configure registry credentials, and review external CLI requirements.

Read time 3 minutes

Last updated 10 hours ago

Unity provides

install-vpctl.sh

as part of your on-premises onboarding package. Once you have the script, run:


./install-vpctl.sh latest

This page explains the script's options, the external CLIs that vpctl uses for specific operations, and how to configure the registry credentials vpctl uses to pull releases.

Requirements

vpctl is a single Go binary, it has no runtime dependencies of its own. External CLIs are required only for operations that shell out to them:

You need...	Required for...
`oras` CLI	The install script ( `install-vpctl.sh` shells out to `oras` to pull the binary)
`docker` CLI, plus `docker login` to source and target registries	`vpctl artifact sync images` (uses `docker pull` / `tag` / `push` / `manifest inspect` / `rmi` )
`docker login` (to populate `~/.docker/config.json` )	`vpctl artifact sync oras` and remote OCI Helm chart pulls — `oras-go` reads credentials from the Docker credential store
`helm` CLI on `PATH`	`vpctl release deploy --format helm` and `vpctl release uninstall`
`kubectl` CLI on `PATH` , plus a kubeconfig	`vpctl secret deploy` , `vpctl release deploy --format argocd` (applies one `Application` CRD), `vpctl release uninstall` (for `templateApply` charts)
`cue` CLI (optional)	Only if you want to validate `manifest.yaml` outside vpctl after `vpctl manifest schema --export` . The schema is embedded in the binary, so `vpctl manifest validate` works without it

All other vpctl commands run without external CLI dependencies.

Install the vpctl binary

The install script automatically detects your OS and architecture and downloads the correct binary from the Unity registry.

Prerequisites: You need registry credentials (username and password). Unity provides these credentials.

The script supports interactive mode for users and non-interactive mode for CI and automation.

Interactive mode

Run the script without setting credentials. It prompts you for your username and password:
```
./install-vpctl.sh latest
```
You can also pin a specific version:
```
./install-vpctl.sh 0.3.1
```

Enter your credentials at the prompt:


[install-vpctl] Logging in to uccmpprivatecloud.azurecr.io (interactive)...[install-vpctl] Please enter your registry credentials:Username: <your-username>Password: <your-password>

Non-interactive mode for CI and automation

For automated environments, set both

ORAS_USERNAME

and

ORAS_PASSWORD

environment variables:


export ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-vpctl.sh latest

You can also pin a specific version:


export ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-vpctl.sh 0.3.1

Custom installation directory

Specify a custom installation directory as the second argument:


./install-vpctl.sh latest /opt/bin

Script actions

The script performs the following actions:

Auto-detects your platform (
```
linux
```
/
```
darwin
```
/
```
windows
```
) and architecture (
```
amd64
```
/
```
arm64
```
).
Checks whether the
```
oras
```
CLI is installed and prompts you to install it if needed.
Authenticates to the registry by using interactive or non-interactive mode based on environment variables.
Downloads and extracts the correct vpctl binary.
Installs it to
```
/usr/local/bin
```
or the directory you specify.
Verifies the installation by running
```
vpctl version
```
.

Environment variables

Variable	Required	Default	Description
`ORAS_USERNAME`	No*	-	Registry username (for non-interactive mode)
`ORAS_PASSWORD`	No*	-	Registry password (for non-interactive mode)
`ORAS_REGISTRY`	No	`uccmpprivatecloud.azurecr.io`	Registry URL

* Both

ORAS_USERNAME

and

ORAS_PASSWORD

must be set together for non-interactive mode, or both unset for interactive mode.

Configure registry credentials

Before you can pull releases, configure your registry credentials.

Run the interactive configuration command:
```
vpctl configure
```
The command prompts you for:
- Username
- Password
The registry defaults to
```
uccmpprivatecloud.azurecr.io
```
. To configure credentials for a different registry, pass it as a positional argument:
```
vpctl configure set <registry-url>
```
.
This securely stores credentials in your home directory.
Alternatively, configure credentials non-interactively. The registry argument is positional and defaults to
```
uccmpprivatecloud.azurecr.io
```
. You can provide the password by using one of the following methods, listed from most to least secure for automation:

--password-stdin
This is recommended for CI/CD. Use

--password-stdin

to read the password from standard input. This method prevents the password from appearing in your shell history or the process list:


echo "$REGISTRY_PASSWORD" | vpctl configure set <registry-url> --username "$REGISTRY_USERNAME" --password-stdin

Use the

VPCTL_PASSWORD

environment variable together with

VPCTL_USERNAME

to supply the credentials through environment variables when piping isn't convenient:


export VPCTL_USERNAME=<username>export VPCTL_PASSWORD=<password>vpctl configure set <registry-url>

Use --password
to pass the password as a flag. This option is available only for backward compatibility and isn't recommended:


vpctl configure set <registry-url> --username <username> --password <password>

Warning

Passing

--password

on the command line exposes the password in your shell history (such as

.bash_history

.zsh_history

) and in the process list (

ps aux

vpctl

also writes a warning to

stderr

when you use this option. For automation, use

--password-stdin

VPCTL_PASSWORD

. or run the interactive

vpctl configure

command instead.

You can't use

--password

and

--password-stdin

together. If you don't specify either option,

vpctl

prompts you for the password interactively. If stdin isn't a terminal and

VPCTL_PASSWORD

isn't set, the command exits with an error instead of hanging.

View configuration


vpctl configure get

Delete credentials

The registry argument is positional and defaults to

uccmpprivatecloud.azurecr.io


vpctl configure delete <registry-url>

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Self-Hosted Deployment

Amazon Web Services

Microsoft Azure

On premises

vpctl

Self-Hosted Deployment

Install vpctl

Requirements

You need...

Required for...

Install the vpctl binary

Interactive mode

Non-interactive mode for CI and automation

Custom installation directory

Script actions

Environment variables

Variable

Required

Default

Description

Configure registry credentials

View configuration

Delete credentials