Command Reference: rdctl

rdctl is a command-line tool, included in Rancher Desktop that enables command-line access to GUI features. rdctl is developed to help users with tasks such as scripting (for automation, CI/CD), troubleshooting, remote management, etc. The current version of rdctl supports the below commands (with support for more commands to be added in upcoming releases):

Command Reference: rdctl - 图1info

As the current version of rdctl is experimental, all subcommand names, their arguments, and their output are still subject to change.

Command Reference: rdctl - 图2warning

The Rancher Desktop application must be running for the following commands:

Command List

  • rdctl list-settings
  • rdctl set
  • rdctl shutdown

Command Reference: rdctl - 图3note

For many rdctl commands, there are corresponding API calls that can be applied. Listed below are the available commands shown in both formats. The api examples will assume curl as the tool being used to talk to the API.

rdctl or rdctl help

Run rdctl or rdctl help to see the list of available commands.

Example Output

  1. > rdctl help
  2. The eventual goal of this CLI is to enable any UI-based operation to be done from the command-line as well.
  3. Usage:
  4. rdctl [command]
  5. Available Commands:
  6. api Run API endpoints directly
  7. completion Generate the autocompletion script for the specified shell
  8. factory-reset Clear all the Rancher Desktop state and shut it down.
  9. help Help about any command
  10. list-settings Lists the current settings.
  11. set Update selected fields in the Rancher Desktop UI and restart the backend.
  12. shell Run an interactive shell or a command in a Rancher Desktop-managed VM
  13. shutdown Shuts down the running Rancher Desktop application
  14. start Start up Rancher Desktop, or update its settings.
  15. version Shows the CLI version.
  16. Flags:
  17. --config-path string config file (default /Users/jan/Library/Application Support/rancher-desktop/rd-engine.json)
  18. -h, --help help for rdctl
  19. --host string default is localhost; most useful for WSL
  20. --password string overrides the password setting in the config file
  21. --port string overrides the port setting in the config file
  22. --user string overrides the user setting in the config file
  23. Use "rdctl [command] --help" for more information about a command.

rdctl api

Run rdctl api / to list all endpoints globally.

Example Output

  1. $ rdctl api / | jq -r .[]
  2. GET /
  3. GET /v0
  4. GET /v1
  5. GET /v1/about
  6. GET /v1/diagnostic_categories
  7. GET /v1/diagnostic_checks
  8. POST /v1/diagnostic_checks
  9. GET /v1/diagnostic_ids
  10. PUT /v1/factory_reset
  11. PUT /v1/propose_settings
  12. GET /v1/settings
  13. PUT /v1/settings
  14. PUT /v1/shutdown
  15. GET /v1/transient_settings
  16. PUT /v1/transient_settings

rdctl api /vX

Run rdctl api /v1 to list all endpoints in version 1.

Example Output

  1. $ rdctl api /v1 | jq -r .[]
  2. GET /v1
  3. GET /v1/about
  4. GET /v1/diagnostic_categories
  5. GET /v1/diagnostic_checks
  6. POST /v1/diagnostic_checks
  7. GET /v1/diagnostic_ids
  8. PUT /v1/factory_reset
  9. PUT /v1/propose_settings
  10. GET /v1/settings
  11. PUT /v1/settings
  12. PUT /v1/shutdown
  13. GET /v1/transient_settings
  14. PUT /v1/transient_settings

rdctl api /v0/settings

rdctl api [endpoints] are commands that are most useful for users working directly with the API itself, and therefore they would not be for everyday use, such as rdctl set might be. For example,

a command such as

  1. rdctl api /v0/settings --method PUT --body '{"kubernetes": {"enabled": false}}'

is the same as

  1. rdctl set --kubernetes-enabled=false

but less concise and user-friendly.

rdctl create-profile

Generates a deployment profile for Rancher Desktop settings in either macOS .plist or Windows .reg format.

  1. rdctl create-profile <options> <options-input>

Options & Example Command

Options

  1. --input [FILE] File containing a JSON document.
  2. --body [JSON] Command-line option containing a JSON document
  3. --from-settings Use current settings.
  4. --output [plist, reg] An output of .plist files for macOS and .reg files for Windows.
  5. Additional options for --output reg:
  6. --type [locked, defaults] The locked field is set as default, otherwise the default type can be specified.
  7. --hive [hklm, hkcu] The hklm field is set as default, otherwise hkcu can be specified.

Example

  1. rdctl create-profile --output reg --hive=Hkcu --from-settings

rdctl extension install

Installs a Rancher Desktop extension.

  1. rdctl extension install <image-id>

Options & Example Output

Options

  1. --force Avoids any interactivity.
  2. <image-id>:<tag> The <tag> is optional, e.g. splatform/epinio-docker-desktop:latest.

Example

  1. $ rdctl extension install docker/logs-explorer-extension:0.2.2
  2. Installing image docker/logs-explorer-extension:0.2.2

rdctl extension ls

Lists currently installed images.

  1. rdctl extension ls

Example Output

Example

  1. $ rdctl extension ls
  2. Extension IDs
  3. docker/logs-explorer-extension:0.2.2

rdctl extension uninstall

Uninstalls a Rancher Desktop extension.

  1. rdctl extension uninstall <image-id>

Options & Example Output

Options

  1. <image-id>:<tag> The <tag> is optional, e.g. splatform/epinio-docker-desktop:latest.

Example

  1. $ rdctl extension uninstall docker/logs-explorer-extension:0.2.2
  2. Uninstalling image docker/logs-explorer-extension:0.2.2: Deleted docker/logs-explorer-extension:0.2.2

rdctl list-settings

  • CLI
  • API

Run rdctl list-settings to see the current active configuration.

Options & Example Output

Options

  1. > rdctl list-settings --help
  2. Lists the current settings in JSON format.
  3. Usage:
  4. rdctl list-settings [flags]
  5. Flags:
  6. -h, --help help for list-settings
  7. Global Flags:
  8. --config-path string config file (default /Users/{username}/Library/Application Support/rancher-desktop/rd-engine.json)
  9. --host string default is localhost; most useful for WSL
  10. --password string overrides the password setting in the config file
  11. --port string overrides the port setting in the config file
  12. --user string overrides the user setting in the config file

Example

  1. > rdctl list-settings
  2. {
  3. "version": 6,
  4. "application": {
  5. "adminAccess": false,
  6. "pathManagementStrategy": "rcfiles",
  7. "updater": {
  8. "enabled": false
  9. },
  10. "debug": false,
  11. "telemetry": {
  12. "enabled": true
  13. },
  14. "autoStart": false,
  15. "startInBackground": false,
  16. "hideNotificationIcon": false,
  17. "window": {
  18. "quitOnClose": false
  19. }
  20. },
  21. "virtualMachine": {
  22. "memoryInGB": 6,
  23. "numberCPUs": 2,
  24. "hostResolver": true
  25. },
  26. "WSL": {
  27. "integrations": {}
  28. },
  29. "containerEngine": {
  30. "allowedImages": {
  31. "enabled": false,
  32. "patterns": [
  33. "docker.io"
  34. ]
  35. },
  36. "name": "moby"
  37. },
  38. "kubernetes": {
  39. "version": "",
  40. "port": 6443,
  41. "enabled": false,
  42. "options": {
  43. "traefik": true,
  44. "flannel": true
  45. },
  46. "ingress": {
  47. "localhostOnly": false
  48. }
  49. },
  50. "portForwarding": {
  51. "includeKubernetesServices": false
  52. },
  53. "images": {
  54. "showAll": true,
  55. "namespace": "k8s.io"
  56. },
  57. "diagnostics": {
  58. "showMuted": false,
  59. "mutedChecks": {}
  60. },
  61. "experimental": {
  62. "virtualMachine": {
  63. "type": "qemu",
  64. "useRosetta": false,
  65. "socketVMNet": false,
  66. "mount": {
  67. "type": "reverse-sshfs",
  68. "9p": {
  69. "securityModel": "none",
  70. "protocolVersion": "9p2000.L",
  71. "msizeInKB": 128,
  72. "cacheMode": "mmap"
  73. }
  74. },
  75. "networkingTunnel": false
  76. }
  77. },
  78. "extensions": {
  79. "docker/logs-explorer-extension:0.2.2": true
  80. }
  81. }

Run the following API call to see the current active configuration:

Example Output

  1. curl -s -H "Authorization: Basic $AUTH" http://localhost:6107/v0/settings -X GET

Note: Using -X GET is optional. You could also just use the preceding command by itself.

rdctl set

  • CLI
  • API

Run rdctl set [flags] to set properties. In most of the cases, Kubernetes would be reset on running the set command. You can set multiple properties by chaining in a single command. See some examples below.

Example Output

  1. > rdctl set --kubernetes-enabled=false
  2. > rdctl set --container-engine docker --kubernetes-version 1.21.2

Run the following API call to set properties:

Example Output

  1. curl -s -H "Authorization: Basic $AUTH" http://localhost:6107/v0/settings -d '{ "kubernetes": { "containerEngine": "docker", "enabled": false, "version":"1.23.5" }}' -X PUT

rdctl shutdown

  • CLI
  • API

Run rdctl shutdown to gracefully shut down Rancher Desktop.

Example Output

  1. > rdctl shutdown
  2. Shutting down.

Run the following API call to shut down Rancher Desktop:

Example Output

  1. shutdown: curl -s -H "Authorization: Basic $AUTH" http://localhost:6107/v0/shutdown -X PUT

rdctl start

  • CLI
  • API

Run rdctl start to ensure that Rancher Desktop is running and configured as requested.

Options & Example Command

Options:

  1. Usage:
  2. rdctl start [flags]
  3. Flags:
  4. --application.admin-access enable privileged operations
  5. --application.auto-start start app when logging in
  6. --application.debug generate more verbose logging
  7. --application.hide-notification-icon don't show notification icon
  8. --application.path-management-strategy string update PATH to include ~/.rd/bin (allowed values: [manual, rcfiles])
  9. --application.start-in-background start app without window
  10. --application.telemetry.enabled allow collection of anonymous statistics
  11. --application.updater.enabled automatically update to the latest release
  12. --application.window.quit-on-close terminate app when the main window is closed
  13. --container-engine.allowed-images.enabled only allow images to be pulled that match the allowed patterns
  14. --container-engine.name string set engine (allowed values: [containerd, docker, moby])
  15. --diagnostics.show-muted unhide muted diagnostics
  16. --experimental.virtual-machine.mount.9p.cache-mode string (allowed values: [none, loose, fscache, mmap])
  17. --experimental.virtual-machine.mount.9p.msize-in-kib int maximum packet size
  18. --experimental.virtual-machine.mount.9p.protocol-version string (allowed values: [9p2000, 9p2000.u, 9p2000.L])
  19. --experimental.virtual-machine.mount.9p.security-model string (allowed values: [passthrough, mapped-xattr, mapped-file, none])
  20. --experimental.virtual-machine.mount.type string how directories are shared (allowed values: [reverse-sshfs, 9p, virtiofs])
  21. --experimental.virtual-machine.socket-vmnet use socket-vmnet instead of vde-vmnet
  22. --experimental.virtual-machine.type string (allowed values: [qemu, vz])
  23. --experimental.virtual-machine.use-rosetta
  24. -h, --help help for start
  25. --images.namespace string select only images from this namespace (containerd only)
  26. --images.show-all show system images on Images page
  27. --kubernetes.enabled run Kubernetes
  28. --kubernetes.options.flannel use flannel networking; disable to install your own CNI
  29. --kubernetes.options.traefik install and run traefik
  30. --kubernetes.port int apiserver port
  31. --kubernetes.version string choose which version of Kubernetes to run
  32. --no-modal-dialogs avoid displaying dialog boxes
  33. -p, --path string path to main executable
  34. --port-forwarding.include-kubernetes-services show Kubernetes system services on Port Forwarding page
  35. --virtual-machine.memory-in-gb int reserved RAM size
  36. --virtual-machine.number-cpus int reserved number of CPUs
  37. Global Flags:
  38. --config-path string config file (default /Users/{username}/Library/Application Support/rancher-desktop/rd-engine.json)
  39. --host string default is localhost; most useful for WSL
  40. --password string overrides the password setting in the config file
  41. --port string overrides the port setting in the config file
  42. --user string overrides the user setting in the config file

Example:

  1. > rdctl start --container-runtime dockerd -- kubernetes-version 1.19.3

Run the following API call to ensure Rancher Desktop is running and configured, making sure to fill in your respective user and password values:

Example Output

  1. curl -s -H "Authorization: Basic $(echo -n "user:PASSWORD" | base64)"

rdctl version

Run rdctl version to see the current rdctl CLI version.

Example Output

  1. > rdctl version
  2. rdctl client version: 1.1.0, targeting server version: v1