# Running the upc-cli tool

> Prepare your environment and run upc-cli.

The upc-cli tool runs as a one-shot pod inside the Kubernetes cluster hosting the target Self-Hosted Deployment environment. It's invoked with the `kubectl run` command and requires corresponding access to the cluster. The pod calls relevant in-cluster services directly and doesn't require authentication to the Self-Hosted Deployment services.

## Prerequisites

To run upc-cli, you need:

* `kubectl` configured for the target cluster hosting the Self-Hosted Deployment environment.
* Permissions to run pods (through `kubectl run`) in the namespace where the solution is deployed. By default, the namespace is `asset-solutions`.
* An ACR pull secret already configured in the same namespace. The secret is usually created during deployment (with the name `acr-unity-registry`), so no additional actions are required.

The administrator workstation needs only the standard `kubectl` tool.

## Tool invocation

To run upc-cli, use the pattern shown here:

* Everything before `--` is `kubectl` flags.
* Everything after `--` is forwarded to the tool executed inside the pod.
* An administrator should usually put relevant values only in the last line: `<command-group> <command> [args...]`.

### Unix-based shell

To run in a Unix-based shell (Linux, MacOS, WSL on Windows, Git Bash on Windows):

```shell
kubectl run -it upc-cli --rm \
  --image=uccmpprivatecloud.azurecr.io/docker/upc-cli:latest \
  -n asset-solutions \
  --restart=Never \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"acr-unity-registry"}]}}' \
  -- \
  --fqdn http://mini-usf:8080 \
  --path-prefix="" \
  --no-auth \
  <command-group> <command> [args...]
```

### Windows shell

All samples on this page work in a Unix-based shell. If you need to run the same natively in a Windows shell:

* Use PowerShell 7.3 or newer. Don't use Windows PowerShell 5.x.
* Replace line continuation characters (`\`) with backticks (`` ` ``):

  ```shell
  kubectl run -it upc-cli --rm `
    --image=uccmpprivatecloud.azurecr.io/docker/upc-cli:latest `
    -n asset-solutions `
    --restart=Never `
    --overrides='{"spec":{"imagePullSecrets":[{"name":"acr-unity-registry"}]}}' `
    -- `
    --fqdn http://mini-usf:8080 `
    --path-prefix="" `
    --no-auth `
    <command-group> <command> [args...]
  ```

### Help

upc-cli also supports the `--help` switch:

```shell
kubectl run -it upc-cli --rm \
  --image=uccmpprivatecloud.azurecr.io/docker/upc-cli:latest \
  -n asset-solutions \
  --restart=Never \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"acr-unity-registry"}]}}' \
  -- \
  --help
```

## Example - list organizations

This example outputs information about the single organization created when deploying Self-Hosted Deployment:

```shell
kubectl run -it upc-cli --rm \
  --image=uccmpprivatecloud.azurecr.io/docker/upc-cli:latest \
  -n asset-solutions \
  --restart=Never \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"acr-unity-registry"}]}}' \
  -- \
  --fqdn http://mini-usf:8080 \
  --path-prefix="" \
  --no-auth \
  orgs list
```

## Usage notes and recommendations

* There is no authentication for intra-cluster calls performed by the tool. You therefore need to treat `kubectl` permissions on the solution namespace as the access boundary, and restrict them accordingly.
* You don't need to enable verbose logging to troubleshoot failed HTTP calls. Failed calls print the full status code, URL, and the response body.

## Next steps

Choose a use case:

* [Manage organization feature flags](/cloud/virtual-private-cloud/admin/upc-cli/upc-cli-scenarios/upc-cli-feature-flags.md)
* [Perform bulk user access management](/cloud/virtual-private-cloud/admin/upc-cli/upc-cli-scenarios/upc-cli-bulk-rbac.md)