# Install vpctl

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

Unity provides `install-vpctl.sh` as part of your on-premises onboarding package. Once you have the script, run:

```sh
./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

1. Run the script without setting credentials. It prompts you for your username and password:

   ```sh
   ./install-vpctl.sh latest
   ```

   You can also pin a specific version:

   ```sh
   ./install-vpctl.sh 0.3.1
   ```

2. Enter your credentials at the prompt:

   ```text
   [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:

```sh
export ORAS_USERNAME="<your-username>"
export ORAS_PASSWORD="<your-password>"

./install-vpctl.sh latest
```

You can also pin a specific version:

```sh
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:

```sh
./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.

1. Run the interactive configuration command:

   ```sh
   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.

2. Alternatively, use the non-interactive configuration command (registry is a positional argument, defaults to `uccmpprivatecloud.azurecr.io`):

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

   > **Warning:**
   >
   > Passing `--password` on the command line writes the password to your shell history file (`.bash_history`, `.zsh_history`) and to the process list (`ps aux`). On a local machine, use the interactive `vpctl configure` command in step 1 instead. Reserve `configure set --password` for CI environments where history isn't retained, and source the value from a secret store rather than a literal.

### View configuration

```sh
vpctl configure get
```

### Delete credentials

The registry argument is positional and defaults to `uccmpprivatecloud.azurecr.io`:

```sh
vpctl configure delete <registry-url>
```