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#

The following global options configure the endpoint, authentication, and output:

Global dpsctl Options

   --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-issuer string                             OIDC issuer URL for browser login endpoint discovery [$DPSCTL_OIDC_ISSUER]
   --oidc-token-url string                          OIDC token endpoint URL override [$DPSCTL_OIDC_TOKEN_URL]
   --oidc-device-auth-url string                    OIDC browser login authorization endpoint URL override [$DPSCTL_OIDC_DEVICE_AUTH_URL]
   --oidc-client-id string, --client-id string      OIDC OAuth client ID [$DPSCTL_OIDC_CLIENT_ID, $DPSCTL_CLIENT_ID]
   --oidc-ca-cert-file string                       Path to PEM CA bundle for OIDC endpoint verification [$DPSCTL_OIDC_CA_CERT_FILE]
   --oidc-allow-http                                Allow HTTP OIDC endpoint URLs for local development only (default: false) [$DPSCTL_OIDC_ALLOW_HTTP]
   --oidc-oauth-scope string, --oauth-scope string  OIDC OAuth scopes to request for browser login or client credentials [$DPSCTL_OIDC_OAUTH_SCOPE, $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

For the server settings that these options must match, refer to Configure Server Authentication.

OIDC Browser Login#

Use --oidc-issuer with login to discover the identity provider’s device authorization and token endpoints. Provide --oidc-client-id and --oidc-oauth-scope when your deployment requires specific values. The browser login defaults are client ID dpsctl and scope dps:api when no client ID or scopes are supplied through flags or saved client settings.

The interactive CLI uses a public OAuth client without a client secret. It sends no secret during device authorization, token exchange, or token refresh. The UI uses a separate public client. Register these clients through Configure OIDC Mode.

You can override the discovered endpoints with --oidc-device-auth-url and --oidc-token-url. Without issuer discovery, provide both endpoint URLs. Use --oidc-ca-cert-file when the provider’s certificate requires a private certificate authority (CA).

Refer to dpsctl login for the sign-in procedure and token selection. Automation uses the separate client credentials flow described in the following section.

OIDC Client Credentials#

In OIDC mode, dpsctl can obtain a service account access token for unattended applications using the OAuth 2.0 client credentials grant. Register a separate confidential client with a client ID and secret for this flow. 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.
`--oidc-client-id`	`DPSCTL_OIDC_CLIENT_ID`	OAuth client ID.
`--oidc-client-secret-file`	`DPSCTL_OIDC_CLIENT_SECRET_FILE`	Path to a file containing the client secret. Prefer this option to an inline secret.
`--oidc-client-secret`	`DPSCTL_OIDC_CLIENT_SECRET`	Inline client secret. Use the secret-file option to keep the value out of process listings and shell history.
`--oidc-oauth-scope`	`DPSCTL_OIDC_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 following details apply to client credentials:

The token endpoint must use HTTPS unless --oidc-allow-http is set.
--oidc-client-secret and --oidc-client-secret-file are hidden from dpsctl --help. Prefer --oidc-client-secret-file or the DPSCTL_OIDC_CLIENT_SECRET_FILE environment variable.
The aliases --client-id, --client-secret, --client-secret-file, and --oauth-scope remain available, with their corresponding DPSCTL_CLIENT_ID, DPSCTL_CLIENT_SECRET, DPSCTL_CLIENT_SECRET_FILE, and DPSCTL_OAUTH_SCOPE environment variables.
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. dpsctl login uses LDAP username/password authentication or OIDC browser login and does not use client credentials.

For service account examples, refer to Obtain a Service Account Token.

Commands#

server-version - Get DPS server version information
login - Log in to the 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`