Skip to main content

Install and Run PX CLI

PX CLI is a unified command-line interface that provides secure, remote access to all Portworx services. This guide walks you through installing PX CLI on your system.

Prerequisites​

Before installing PX CLI, ensure your system meets these requirements:

  • Operating System:
    • Windows 64 bit platforms
    • Linux 64 bit platforms
    • macOS with Apple Silicon
  • Portworx Enterprise:
    • px pxe
      • Portworx Enterprise 3.3 or later
      • kubectl version 1.24 or later
      • Valid kubeconfig with cluster connectivity
    • px pxctl
      • Portworx Enterprise 3.3 or later
      • Valid kubeconfig with cluster connectivity
  • Portworx Backup:
    • Portworx Backup 2.10.0 or later
    • Portworx Backup and Portworx Central service endpoints with HTTP/HTTPS access

Download PX CLI​

  1. Go to Portworx Central and sign in or create an account.
  2. From the left sidebar, select Support.
  3. In the Downloads section, choose the PX CLI binary for your operating system.

Install PX CLI​

Follow the steps below based on your operating system:

  1. Open a terminal and go to the directory where you have the downloaded PX CLI file:

    cd <directory-of-downloaded-file>   # Example: cd ~/Downloads

  2. Extract the archive:

    tar -xzf <downloaded-filename>

  3. Copy the PX CLI binaries to a directory in your PATH:

    sudo cp px/bin/* /usr/local/bin/

  4. Make the binaries executable:

    chmod +x /usr/local/bin/px*

  5. (Optional) Remove the archive and extracted files:

    rm -rf px <downloaded-filename>

Verify the Installation​

  1. Verify that PX CLI is correctly installed:

    px version
    Client Version: <verion-information>

  2. Inspect the list of available components:

    px component list
    The following compatible components are available:
    /usr/local/bin/px-pxe
    /usr/local/bin/px-pxb
    /usr/local/bin/px-pxctl
important

On macOS, you might encounter security warnings when running PX CLI binaries for the first time. If your system shows a security prompt, update your system’s privacy and security settings to allow the binaries to run.

Connect Portworx clusters​

After installing PX CLI, configure it to connect to your Portworx services.

PX CLI can run in two modes:

  • As a kubectl plugin (kubectl px)
  • As a standalone binary (px)

The behavior and command structure are identical in both modes.

Connect Portworx Enterprise cluster​

The Portworx Enterprise component (px pxe) connects through your Kubernetes configuration context.
It uses the same kubeconfig file that kubectl uses to determine which cluster to manage.

  1. Check your current Kubernetes context:

    kubectl config current-context

  2. (Optional) List available contexts to identify the one for your Portworx cluster:

    kubectl config get-contexts

  3. Switch to the correct context:

    kubectl config use-context <your-portworx-cluster-context>

  4. Verify connectivity:

    kubectl cluster-info

  5. Describe the connected Portworx cluster:

    px pxe describe cluster
    Name: px-cluster-int
    UUID: af86ef68-48b6-4dca-a5e4-6def908da8d0
    Status: Ready
    Nodes: 3 (3 online)
    PX Version: 3.2.0.0-8706595

  6. List clusters available in your kubeconfig context:

    px pxe get cluster

  7. List nodes in the cluster:

    px pxe get node

Switch Between Cluster Contexts

px pxe uses the Kubernetes context to determine which Portworx cluster to manage. If you manage multiple clusters, switch between contexts using:

kubectl config use-context <cluster-name>
px pxe get cluster
note

This context-switching feature applies only to the Portworx Enterprise (px pxe) component. Portworx Backup (px pxb) uses direct API endpoints and does not rely on kubeconfig contexts.

Connect Portworx Backup cluster​

The Portworx Backup component (px pxb) connects directly to the Portworx Backup API and PX-Central authentication services.

Prerequisites for Istio service mesh

If you have installed Istio with sidecar injection and Portworx Backup with istio.enabled=true, follow these additional steps to enable PX CLI access:

  1. Create an Istio gateway for gRPC traffic:

    apiVersion: networking.istio.io/v1
    kind: Gateway
    metadata:
      name: pxbackup-grpc-gateway
      namespace: <px-backup>  # Replace with your namespace
    spec:
      selector:
        istio: ingressgateway  # Use the same Istio ingress gateway
      servers:
      - port:
          number: 10002
          name: grpc-pxbackup
          protocol: GRPC
        hosts:
        - "*"

  2. Create a virtual service to route traffic:

    apiVersion: networking.istio.io/v1
    kind: VirtualService
    metadata:
      name: px-backup-virtualservice
      namespace: <px-backup>  # Replace with your namespace
    spec:
      gateways:
      - pxbackup-grpc-gateway  # The new gRPC gateway
      hosts:
      - "*"
      http:
      - match:
        - uri:
            prefix: /
        route:
        - destination:
            host: px-backup.px-backup.svc.cluster.local
            port:
              number: 10002

  3. Patch the Istio ingress gateway service to expose the gRPC port:

    kubectl patch svc istio-ingressgateway -n istio-system --type='json' -p='[
      {
        "op": "add",
        "path": "/spec/ports/-",
        "value": {
          "name": "grpc-pxbackup",
          "port": 10002,
          "targetPort": 10002,
          "protocol": "TCP",
          "nodePort": 31002
        }
      }
    ]'

Follow the steps below to connect PX CLI to your Portworx Backup cluster with basic authentication:

  1. Retrieve the Portworx Backup and PX-Central service endpoints:

    kubectl get svc -n px-backup | grep -E "(px-backup-ui|px-central-ui)"

  2. Initialize PX CLI with endpoint information:

    px pxb init config\
      --px-backup-api-url http://<px-backup-endpoint>:<port> \
      --pxcentral-auth-url http://<px-central-endpoint>:<port>

  3. Authenticate with PX-Central:

    px pxb login

    PX CLI will open a browser window for authentication through PX-Central OAuth. After successful login, credentials are cached locally in ~/.px/config.

  4. Verify your configuration:

    px pxb view config

  5. List available backups to confirm connectivity:

    px pxb get backup

For more information about configuring pxb and authorization, see the following pages:

  • Configure px pxb: Set up API endpoints, authentication URLs, and TLS certificates to establish connection with your Portworx Backup instance.
  • Login: Authenticate with Portworx Backup using browser-based or username/password methods to obtain session tokens.

Upgrade PX CLI​

PX CLI includes a built-in self-upgrade command that checks for newer releases and shows it on the interface. You can upgrade the CLI using the px utilities upgrade command. This command downloads the latest version of PX CLI and updates your installation automatically.

Uninstall PX CLI​

If you need to remove PX CLI from your system, delete the binaries from your PATH.

sudo rm -f /usr/local/bin/px /usr/local/bin/px-* /usr/local/bin/kubectl-px
note
  • The directory ~/.px/ stores cached CLI configurations and authentication tokens for px pxe and px pxb.
  • You can remove it only if you want to reset CLI settings or clear authentication data: 
    rm -rf ~/.px/