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.

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.

Additionally, some examples make use of credentials which can be found in these locations across platforms:

  • Linux: ~/.local/share/rancher-desktop/
  • macOS: ~/Library/Application Support/rancher-desktop/
  • Windows: %LOCALAPPDATA%\rancher-desktop\

Command Reference: rdctl - 图2warning

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

Details

Command List

  • rdctl list-settings
  • rdctl set
  • rdctl shutdown

rdctl or rdctl help

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

Details

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.
  4. Usage:
  5.   rdctl [command]
  7. Available Commands:
  8.   api            Run API endpoints directly
  9.   completion     Generate the autocompletion script for the specified shell
  10.   create-profile Generate a deployment profile in either macOS plist or Windows registry format
  11.   extension      Manage extensions
  12.   factory-reset  Clear all the Rancher Desktop state and shut it down.
  13.   help           Help about any command
  14.   list-settings  Lists the current settings.
  15.   set            Update selected fields in the Rancher Desktop UI and restart the backend.
  16.   shell          Run an interactive shell or a command in a Rancher Desktop-managed VM
  17.   shutdown       Shuts down the running Rancher Desktop application
  18.   snapshot       Manage Rancher Desktop snapshots
  19.   start          Start up Rancher Desktop, or update its settings.
  20.   version        Shows the CLI version.
  22. Flags:
  23.       --config-path string   config file (default ~/$HOME/rancher-desktop/rd-engine.json)
  24.   -h, --help                 help for rdctl
  25.       --host string          default is 127.0.0.1; most useful for WSL
  26.       --password string      overrides the password setting in the config file
  27.       --port string          overrides the port setting in the config file
  28.       --user string          overrides the user setting in the config file
  30. Use "rdctl [command] --help" for more information about a command.

rdctl api

Run rdctl api / to list all endpoints globally.

Details

Example Output

  1. $ rdctl api / | jq -r .[]
  2. GET /
  3. GET /v0
  4. GET /v1
  5. GET /v1/about
  6. GET /v1/backend_state
  7. PUT /v1/backend_state
  8. GET /v1/diagnostic_categories
  9. GET /v1/diagnostic_checks
  10. POST /v1/diagnostic_checks
  11. GET /v1/diagnostic_ids
  12. GET /v1/extensions
  13. POST /v1/extensions/install
  14. POST /v1/extensions/uninstall
  15. PUT /v1/factory_reset
  16. PUT /v1/propose_settings
  17. GET /v1/settings
  18. PUT /v1/settings
  19. GET /v1/settings/locked
  20. PUT /v1/shutdown
  21. POST /v1/snapshot/restore
  22. GET /v1/snapshots
  23. DELETE /v1/snapshots
  24. POST /v1/snapshots
  25. GET /v1/transient_settings
  26. PUT /v1/transient_settings

rdctl api /vX

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

Details

Example Output

  1. $ rdctl api /v1 | jq -r .[]
  2. GET /v1
  3. GET /v1/about
  4. GET /v1/backend_state
  5. PUT /v1/backend_state
  6. GET /v1/diagnostic_categories
  7. GET /v1/diagnostic_checks
  8. POST /v1/diagnostic_checks
  9. GET /v1/diagnostic_ids
  10. GET /v1/extensions
  11. POST /v1/extensions/install
  12. POST /v1/extensions/uninstall
  13. PUT /v1/factory_reset
  14. PUT /v1/propose_settings
  15. GET /v1/settings
  16. PUT /v1/settings
  17. GET /v1/settings/locked
  18. PUT /v1/shutdown
  19. POST /v1/snapshot/restore
  20. GET /v1/snapshots
  21. DELETE /v1/snapshots
  22. POST /v1/snapshots
  23. GET /v1/transient_settings
  24. PUT /v1/transient_settings

rdctl api /v1/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 /v1/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>

Details

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.
  6. Additional options for --output reg:
  7. --type [locked, defaults]   The locked field is set as default, otherwise the default type can be specified.
  8. --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>

Details

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: Created

rdctl extension ls

Lists currently installed images.

  1. rdctl extension ls

Details

Example Output

Example

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

rdctl extension uninstall

Uninstalls a Rancher Desktop extension.

  1. rdctl extension uninstall <image-id>

Details

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.

Details

Options & Example Output

Options

  2. > rdctl list-settings --help 
  3. Lists the current settings in JSON format.
  5. Usage:
  6.   rdctl list-settings [flags]
  8. Flags:
  9.   -h, --help   help for list-settings
  11. Global Flags:
  12.       --config-path string   config file (default ~/HOME/rancher-desktop/rd-engine.json)
  13.       --host string          default is 127.0.0.1; most useful for WSL
  14.       --password string      overrides the password setting in the config file
  15.       --port string          overrides the port setting in the config file
  16.       --user string          overrides the user setting in the config file

Example Output Using macOS Environment

  1. > rdctl list-settings
  2. {
  3.   "version": 10,
  4.   "application": {
  5.     "adminAccess": true,
  6.     "debug": false,
  7.     "extensions": {
  8.       "allowed": {
  9.         "enabled": false,
  10.         "list": []
  11.       },
  12.       "installed": {}
  13.     },
  14.     "pathManagementStrategy": "rcfiles",
  15.     "telemetry": {
  16.       "enabled": true
  17.     },
  18.     "updater": {
  19.       "enabled": true
  20.     },
  21.     "autoStart": false,
  22.     "startInBackground": false,
  23.     "hideNotificationIcon": false,
  24.     "window": {
  25.       "quitOnClose": false
  26.     }
  27.   },
  28.   "containerEngine": {
  29.     "allowedImages": {
  30.       "enabled": false,
  31.       "patterns": [],
  32.       "locked": false
  33.     },
  34.     "name": "containerd"
  35.   },
  36.   "virtualMachine": {
  37.     "memoryInGB": 4,
  38.     "numberCPUs": 2,
  39.     "hostResolver": true
  40.   },
  41.   "WSL": {
  42.     "integrations": {}
  43.   },
  44.   "kubernetes": {
  45.     "version": "1.28.2",
  46.     "port": 6443,
  47.     "enabled": true,
  48.     "options": {
  49.       "traefik": true,
  50.       "flannel": true
  51.     },
  52.     "ingress": {
  53.       "localhostOnly": false
  54.     }
  55.   },
  56.   "portForwarding": {
  57.     "includeKubernetesServices": false
  58.   },
  59.   "images": {
  60.     "showAll": true,
  61.     "namespace": "k8s.io"
  62.   },
  63.   "diagnostics": {
  64.     "showMuted": true,
  65.     "mutedChecks": {
  66.       "STATIC_FALSE": true
  67.     }
  68.   },
  69.   "experimental": {
  70.     "virtualMachine": {
  71.       "type": "vz",
  72.       "useRosetta": false,
  73.       "socketVMNet": true,
  74.       "mount": {
  75.         "type": "reverse-sshfs",
  76.         "9p": {
  77.           "securityModel": "none",
  78.           "protocolVersion": "9p2000.L",
  79.           "msizeInKib": 128,
  80.           "cacheMode": "mmap"
  81.         }
  82.       },
  83.       "networkingTunnel": false,
  84.       "proxy": {
  85.         "enabled": false,
  86.         "address": "",
  87.         "password": "",
  88.         "port": 3128,
  89.         "username": "",
  90.         "noproxy": [
  91.           "0.0.0.0/8",
  92.           "10.0.0.0/8",
  93.           "127.0.0.0/8",
  94.           "169.254.0.0/16",
  95.           "172.16.0.0/12",
  96.           "192.168.0.0/16",
  97.           "224.0.0.0/4",
  98.           "240.0.0.0/4"
  99.         ]
  100.       }
  101.     }
  102.   }
  103. }

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

Details

Example Command

  1. curl -s -H "Authorization: Basic $AUTH" http://localhost:6107/v1/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.

Details

Example Command

  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:

Details

Example Command

  1. curl -s -H "Authorization: Basic $AUTH" http://localhost:6107/v1/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.

Details

Example Output

  1. > rdctl shutdown
  2. Shutting down.

Run the following API call to shut down Rancher Desktop:

Details

Example Command

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

rdctl snapshot

Run rdctl snapshot to store the current configuration of your virtual machine and all associated settings as a snapshot.

Details

Options & Example Commands

Options

  1. Usage:
  2.   rdctl snapshot [command]
  4. Available Commands:
  5.   create      Create a snapshot
  6.   delete      Delete a snapshot
  7.   list        List snapshots
  8.   restore     Restore a snapshot
  9.   unlock      Remove snapshot lock
  11. Flags:
  12.   -h, --help   help for snapshot
  14. Global Flags:
  15.       --config-path string   config file (default /Users/[username]/Library/Application Support/rancher-desktop/rd-engine.json)
  16.       --host string          default is 127.0.0.1; most useful for WSL
  17.       --password string      overrides the password setting in the config file
  18.       --port string          overrides the port setting in the config file
  19.       --user string          overrides the user setting in the config file
  21. Use "rdctl snapshot [command] --help" for more information about a command.

Example

  4. $ rdctl snapshot create example_snapshot
  5. $ rdctl snapshot delete example_snapshot
  6. $ rdctl snapshot list --json
  7. {"created":"2023-10-23T13:11:45.311273-07:00","name":"Snap_2023-10-23_13_11_25","description":""}
  8. {"created":"2023-10-23T13:13:34.439465-07:00","name":"Example_Snapshot_1","description":"Snapshot descriptions can be entered in this field."}

rdctl start

  • CLI
  • API

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

Details

Options & Example Command

Options:

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

Details

Example Command

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

rdctl version

Run rdctl version to see the current rdctl CLI version.

Details

Example Output

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