dpsctl#

Overview#

dpsctl is a CLI used to query or send control commands to the Dynamic Power Software.

Usage#

dpsctl [global options] [command [command options]]

Flags#

   --host string, -H string                       DPS gRPC host address (default: "localhost") [$DPSCTL_HOST]
   --port uint, -p uint                           DPS gRPC port number (default: 50051) [$DPSCTL_PORT]
   --grpc-timeout duration, -D duration           gRPC timeout (duration) (default: 1m0s) [$DPSCTL_GRPC_TIMEOUT]
   --resolve string                               Provide a custom address for a hostname in format 'host:port:addr' (similar to curl --resolve)
   --credentials-path string, -c string           The path to the credentials configuration file (default: "${HOME}/.dpsctl/credentials.yaml") [$DPSCTL_CREDENTIALS_PATH]
   --oidc-token-url string                        OIDC token endpoint URL for OAuth client credentials [$DPSCTL_OIDC_TOKEN_URL]
   --client-id string                             OIDC OAuth client ID [$DPSCTL_CLIENT_ID]
   --oidc-ca-cert-file string                     Path to PEM CA bundle for OIDC token endpoint verification [$DPSCTL_OIDC_CA_CERT_FILE]
   --oidc-allow-http                              Allow HTTP OIDC token endpoint URLs for local development only (default: false) [$DPSCTL_OIDC_ALLOW_HTTP]
   --oauth-scope string [ --oauth-scope string ]  OAuth scopes to request for client credentials [$DPSCTL_OAUTH_SCOPE]
   --insecure                                     Disable TLS encryption for gRPC connections (default: false) [$DPSCTL_INSECURE]
   --insecure-tls-skip-verify                     Disable TLS certificate validation for gRPC connections (default: false) [$DPSCTL_INSECURE_TLS_SKIP_VERIFY]
   --ca-cert-path string                          Path to CA certificate file for TLS verification [$DPSCTL_CA_CERT_PATH]
   --client-cert-path string                      Path to client certificate file for mTLS authentication [$DPSCTL_CLIENT_CERT_PATH]
   --client-key-path string                       Path to client private key file for mTLS authentication [$DPSCTL_CLIENT_KEY_PATH]
   --auth-mode string                             Authentication mode. Valid values are: auto, jwt, mtls (default: "auto") [$DPSCTL_AUTH_MODE]
   --output string, -o string                     Output format. Valid values are: json, yaml (default: "json") [$DPSCTL_OUTPUT]
   --no-retry                                     Whether to avoid retrying a retryable command (default: false) [$DPSCTL_NO_RETRY]
   --no-version-check                             Skip the preflight dpsctl/dps-server version mismatch check (default: false) [$DPSCTL_NO_VERSION_CHECK]
   --max-retries int                              The number of retries to attempt on a retryable command (default: 3) [$DPSCTL_MAX_RETRIES]
   --retry-delay int                              The time to wait between retries, in seconds, for a retryable command (default: 3) [$DPSCTL_RETRY_DELAY]
   --log-file string                              Path to log file (default: "${HOME}/.dpsctl/dpsctl.log") [$DPSCTL_LOG_FILE]
   --debug                                        Enable debug logging (default: false) [$DEBUG]
   --help, -h                                     show help
   --version, -v                                  print the version

OIDC OAuth client credentials#

When DPS is deployed in OIDC mode, dpsctl can obtain a service-account access token for non-interactive automation using the OAuth 2.0 Client Credentials grant. The following global flags configure that flow; each has an environment-variable equivalent.

Flag	Environment variable	Description
`--oidc-token-url`	`DPSCTL_OIDC_TOKEN_URL`	OIDC token endpoint URL for the client-credentials grant.
`--client-id`	`DPSCTL_CLIENT_ID`	OAuth client ID.
`--client-secret-file`	`DPSCTL_CLIENT_SECRET_FILE`	Path to a file containing the client secret. Preferred over `--client-secret`.
`--client-secret`	`DPSCTL_CLIENT_SECRET`	Client secret provided inline. Discouraged because it is visible in process listings and shell history.
`--oauth-scope`	`DPSCTL_OAUTH_SCOPE`	OAuth scope to request. Repeatable. Defaults to `dps:api` when unset.
`--oidc-ca-cert-file`	`DPSCTL_OIDC_CA_CERT_FILE`	PEM CA bundle used to verify the token endpoint’s TLS certificate (for a private or enterprise CA).
`--oidc-allow-http`	`DPSCTL_OIDC_ALLOW_HTTP`	Allow an `http://` token endpoint. Local development only.

The token endpoint must use HTTPS unless --oidc-allow-http is set.
--client-secret and --client-secret-file are hidden from dpsctl --help to avoid surfacing secrets; prefer --client-secret-file or the DPSCTL_CLIENT_SECRET_FILE environment variable.
Acquired tokens are cached in the credentials file and reused while valid when the token URL, client ID, and scopes match.
If DPS is configured with an OIDC allowedClientIds allowlist, the client ID must be listed there; otherwise the request is rejected as invalid_authorized_party.
Client credentials apply to normal commands only. dpsctl login performs interactive username/password authentication and does not use them.

Refer to Automation Accounts for a full walkthrough and examples.

Commands#

server-version - Get DPS server version information
login - Login to DPS server
topology - Topology operations
resource-group - Resource Group operations
gpu-policy - Set GPU power policies
device - Manage devices
check - DPS diagnostic tools
policy - Policy operations
settings - Settings operations
import - Import operations
verify - Verify DPS deployment status
validate - Validation operations (dry-run analysis without persisting state)
auth - Authentication operations
nvgrid - NvGrid power management operations
task - Task operations
agent - Agent operations
help, h - Shows a list of commands or help for one command

Aliases#

Command	Aliases
`topology`	`tp`
`resource-group`	`rg`
`validate`	`val`
`help`	`h`