Installing dpsctl

Overview

This guide provides a step-by-step process for installing the DPS command-line client.

There are two install paths:

Install via Container (recommended) - Run dpsctl directly from the published container image, optionally fronted by a small shell wrapper so it behaves like a native dpsctl binary.
Install Pre-built Binary - Download a platform-specific dpsctl binary.

Prerequisites

Linux or macOS operating system
amd64 or arm64 architecture
Docker (or a compatible OCI runtime such as Podman) for the container install path

Install via Container (Recommended)

dpsctl is published as a container image at nvcr.io/nvidia/dpsctl:<version> (the examples below use 0.8.0). This is the quickest way to get started — no binary download or platform selection required.

One-shot `docker run`

Run any dpsctl subcommand directly:

docker run --rm -it --network host \
  nvcr.io/nvidia/dpsctl:0.8.0 \
  login --host api.dps --port 443 --insecure-tls-skip-verify

Notes:

--network host lets the container reach localhost and any cluster DNS names that resolve on your host.

Install as a `dpsctl` Shim

For a smoother experience, install a small wrapper script as ~/.local/bin/dpsctl so every invocation transparently runs the container with sensible defaults (HOME mount, working-directory mount, TTY detection, env-var pass-through):

mkdir -p ~/.local/bin
cat > ~/.local/bin/dpsctl <<'EOF'
#!/bin/bash
# dpsctl wrapper — proxies all calls to the Docker image.
# Override at runtime, e.g.:
#   DPSCTL_VERSION=0.8.1 dpsctl ...
#   DPSCTL_IMAGE=nvcr.io/nvidia/dpsctl DPSCTL_VERSION=0.8.0 dpsctl ...
IMAGE="${DPSCTL_IMAGE:-nvcr.io/nvidia/dpsctl}"
VERSION="${DPSCTL_VERSION:-0.8.0}"
mkdir -p "${HOME}/.dpsctl"
# Resolve real path so symlinks inside PWD work inside the container
WORKSPACE=$(realpath "${PWD}" 2>/dev/null || echo "${PWD}")

# Build mounts: always include HOME and WORKSPACE at their real paths;
# add /Users only when it exists (macOS native or Lima VM with macOS mount)
MOUNTS=(-v "${HOME}:${HOME}" -v "${WORKSPACE}:${WORKSPACE}")
[ -d "/Users" ] && MOUNTS+=(-v "/Users:/Users:ro")

# Always keep stdin attached; only allocate a TTY when running interactively,
# so redirected/captured output is not corrupted by terminal control sequences.
TTY_FLAGS=(-i)
if [ -t 0 ] && [ -t 1 ]; then
  TTY_FLAGS+=(-t)
fi

exec docker run --rm \
  --network host \
  "${TTY_FLAGS[@]}" \
  --user "$(id -u):$(id -g)" \
  -e HOME="${HOME}" \
  "${MOUNTS[@]}" \
  -w "${WORKSPACE}" \
  -e DPSCTL_USERNAME \
  -e DPSCTL_PASSWORD \
  -e DPSCTL_HOST \
  -e DPSCTL_PORT \
  -e DPSCTL_INSECURE_TLS_SKIP_VERIFY \
  -e DPSCTL_INSECURE \
  -e DPSCTL_GRPC_TIMEOUT \
  -e DPSCTL_OUTPUT \
  "${IMAGE}:${VERSION}" \
  "$@"
EOF
chmod +x ~/.local/bin/dpsctl

Then make sure ~/.local/bin is on your PATH:

export PATH="${HOME}/.local/bin:${PATH}"

What the wrapper does:

Mounts $HOME so credentials at ~/.dpsctl/credentials.yaml persist across invocations.
Mounts the current working directory at the same path inside the container so commands like dpsctl topology import ./datacenter.json Just Work.
Uses --network host so localhost and cluster-internal DNS names resolve from inside the container.
Passes through the standard DPSCTL_* environment variables (host, port, credentials, output format, etc.).
Allocates a TTY only when stdin/stdout are interactive, so piped output stays clean.

Pinning a Different Version

DPSCTL_IMAGE and DPSCTL_VERSION can be overridden independently — the wrapper joins them as ${IMAGE}:${VERSION}:

# Use a different image tag for one invocation
DPSCTL_VERSION=0.8.1 dpsctl --version

# Override both repo and tag (e.g. internal mirror)
DPSCTL_IMAGE=nvcr.io/nvidia/dpsctl DPSCTL_VERSION=0.8.1 dpsctl --version

Examples Using the Wrapper

Once the shim is on your PATH, every command behaves like a native binary:

dpsctl login --host api.dps --port 443 --insecure-tls-skip-verify
dpsctl topology import ./datacenter.json
dpsctl resource-group list

Install Pre-built Binary (Alternative)

DPS provides pre-built binaries for the following platforms:

Linux
macOS

Download dpsctl from the NVIDIA NVOnline Portal.

VERSION="v0.8.0"  # e.g. v1.0.0
OS="linux"        # e.g. linux or darwin
ARCH="amd64"      # e.g. amd64, arm64

# Extract the binary
tar -xzf dpsctl_${OS}_${ARCH}_v1-${VERSION}.tgz

# Make it executable
chmod +x dpsctl

# Move to system PATH (optional)
sudo mv dpsctl /usr/local/bin/

# Verify installation
dpsctl --version

Verification

After installation, verify that dpsctl is working correctly:

# Check version
dpsctl --version

# View help
dpsctl --help

Troubleshooting

Permission Issues

# If you get permission denied
chmod +x dpsctl

# If system installation fails
sudo chown $USER:$USER dpsctl

Connection Issues

# Log in to the DPS server
dpsctl login

# Test server functionality
dpsctl verify

Authentication Issues

# Re-login if credentials expire
dpsctl login

# Check credential file
ls -la ~/.dpsctl/credentials.yaml

Next Steps

After installing dpsctl, see:

dpsctl Usage Guide - Complete command reference
Deploy DPS - Set up DPS server