Skip to main content
Version: Next 🚧

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

info

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\
warning

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

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.

Example Output
> rdctl help
The eventual goal of this CLI is to enable any UI-based operation to be done from the command-line as well.

Usage:
rdctl [command]

Available Commands:
api Run API endpoints directly
completion Generate the autocompletion script for the specified shell
create-profile Generate a deployment profile in either macOS plist or Windows registry format
extension Manage extensions
factory-reset Clear all the Rancher Desktop state and shut it down.
help Help about any command
list-settings Lists the current settings.
set Update selected fields in the Rancher Desktop UI and restart the backend.
shell Run an interactive shell or a command in a Rancher Desktop-managed VM
shutdown Shuts down the running Rancher Desktop application
snapshot Manage Rancher Desktop snapshots
start Start up Rancher Desktop, or update its settings.
version Shows the CLI version.

Flags:
--config-path string config file (default ~/$HOME/rancher-desktop/rd-engine.json)
-h, --help help for rdctl
--host string default is 127.0.0.1; most useful for WSL
--password string overrides the password setting in the config file
--port string overrides the port setting in the config file
--user string overrides the user setting in the config file

Use "rdctl [command] --help" for more information about a command.

rdctl api

Run rdctl api / to list all endpoints globally.

Example Output
$ rdctl api / | jq -r .[]
GET /
GET /v0
GET /v1
GET /v1/about
GET /v1/backend_state
PUT /v1/backend_state
GET /v1/diagnostic_categories
GET /v1/diagnostic_checks
POST /v1/diagnostic_checks
GET /v1/diagnostic_ids
GET /v1/extensions
POST /v1/extensions/install
POST /v1/extensions/uninstall
PUT /v1/factory_reset
PUT /v1/propose_settings
GET /v1/settings
PUT /v1/settings
GET /v1/settings/locked
PUT /v1/shutdown
POST /v1/snapshot/restore
GET /v1/snapshots
DELETE /v1/snapshots
POST /v1/snapshots
GET /v1/transient_settings
PUT /v1/transient_settings

rdctl api /vX

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

Example Output
$ rdctl api /v1 | jq -r .[]
GET /v1
GET /v1/about
GET /v1/backend_state
PUT /v1/backend_state
GET /v1/diagnostic_categories
GET /v1/diagnostic_checks
POST /v1/diagnostic_checks
GET /v1/diagnostic_ids
GET /v1/extensions
POST /v1/extensions/install
POST /v1/extensions/uninstall
PUT /v1/factory_reset
PUT /v1/propose_settings
GET /v1/settings
PUT /v1/settings
GET /v1/settings/locked
PUT /v1/shutdown
POST /v1/snapshot/restore
GET /v1/snapshots
DELETE /v1/snapshots
POST /v1/snapshots
GET /v1/transient_settings
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

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

is the same as

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.

rdctl create-profile <options> <options-input>
Options & Example Command

Options

--input [FILE]              File containing a JSON document.
--body [JSON] Command-line option containing a JSON document
--from-settings Use current settings.
--output [plist, reg] An output of .plist files for macOS and .reg files for Windows.

Additional options for --output reg:
--type [locked, defaults] The locked field is set as default, otherwise the default type can be specified.
--hive [hklm, hkcu] The hklm field is set as default, otherwise hkcu can be specified.

Example

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

rdctl extension install

Installs a Rancher Desktop extension.

rdctl extension install <image-id>
Options & Example Output

Options

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

Example

$ rdctl extension install docker/logs-explorer-extension:0.2.2
Installing image docker/logs-explorer-extension:0.2.2: Created

rdctl extension ls

Lists currently installed images.

rdctl extension ls
Example Output

Example

$ rdctl extension ls
Extension IDs

docker/logs-explorer-extension:0.2.2

rdctl extension uninstall

Uninstalls a Rancher Desktop extension.

rdctl extension uninstall <image-id>
Options & Example Output

Options

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

Example

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

rdctl list-settings

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

Options & Example Output

Options


> rdctl list-settings --help
Lists the current settings in JSON format.

Usage:
rdctl list-settings [flags]

Flags:
-h, --help help for list-settings

Global Flags:
--config-path string config file (default ~/HOME/rancher-desktop/rd-engine.json)
--host string default is 127.0.0.1; most useful for WSL
--password string overrides the password setting in the config file
--port string overrides the port setting in the config file
--user string overrides the user setting in the config file

Example Output Using macOS Environment

> rdctl list-settings
{
"version": 10,
"application": {
"adminAccess": true,
"debug": false,
"extensions": {
"allowed": {
"enabled": false,
"list": []
},
"installed": {}
},
"pathManagementStrategy": "rcfiles",
"telemetry": {
"enabled": true
},
"updater": {
"enabled": true
},
"autoStart": false,
"startInBackground": false,
"hideNotificationIcon": false,
"window": {
"quitOnClose": false
}
},
"containerEngine": {
"allowedImages": {
"enabled": false,
"patterns": [],
"locked": false
},
"name": "containerd"
},
"virtualMachine": {
"memoryInGB": 4,
"numberCPUs": 2,
"hostResolver": true
},
"WSL": {
"integrations": {}
},
"kubernetes": {
"version": "1.28.2",
"port": 6443,
"enabled": true,
"options": {
"traefik": true,
"flannel": true
},
"ingress": {
"localhostOnly": false
}
},
"portForwarding": {
"includeKubernetesServices": false
},
"images": {
"showAll": true,
"namespace": "k8s.io"
},
"diagnostics": {
"showMuted": true,
"mutedChecks": {
"STATIC_FALSE": true
}
},
"experimental": {
"virtualMachine": {
"type": "vz",
"useRosetta": false,
"socketVMNet": true,
"mount": {
"type": "reverse-sshfs",
"9p": {
"securityModel": "none",
"protocolVersion": "9p2000.L",
"msizeInKib": 128,
"cacheMode": "mmap"
}
},
"networkingTunnel": false,
"proxy": {
"enabled": false,
"address": "",
"password": "",
"port": 3128,
"username": "",
"noproxy": [
"0.0.0.0/8",
"10.0.0.0/8",
"127.0.0.0/8",
"169.254.0.0/16",
"172.16.0.0/12",
"192.168.0.0/16",
"224.0.0.0/4",
"240.0.0.0/4"
]
}
}
}
}

rdctl set

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 Command
> rdctl set --kubernetes-enabled=false
> rdctl set --container-engine docker --kubernetes-version 1.21.2

rdctl shutdown

Run rdctl shutdown to gracefully shut down Rancher Desktop.

Example Output
> rdctl shutdown
Shutting down.

rdctl snapshot

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

Options & Example Commands

Options

Usage:
rdctl snapshot [command]

Available Commands:
create Create a snapshot
delete Delete a snapshot
list List snapshots
restore Restore a snapshot
unlock Remove snapshot lock

Flags:
-h, --help help for snapshot

Global Flags:
--config-path string config file (default /Users/[username]/Library/Application Support/rancher-desktop/rd-engine.json)
--host string default is 127.0.0.1; most useful for WSL
--password string overrides the password setting in the config file
--port string overrides the port setting in the config file
--user string overrides the user setting in the config file

Use "rdctl snapshot [command] --help" for more information about a command.

Example




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

rdctl start

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

Options & Example Command

Options:

Usage:
rdctl start [flags]

Flags:
--application.admin-access enable privileged operations
--application.auto-start start app when logging in
--application.debug generate more verbose logging
--application.hide-notification-icon don't show notification icon
--application.path-management-strategy string update PATH to include ~/.rd/bin (allowed values: [manual, rcfiles])
--application.start-in-background start app without window
--application.telemetry.enabled allow collection of anonymous statistics
--application.updater.enabled automatically update to the latest release
--application.window.quit-on-close terminate app when the main window is closed
--container-engine.allowed-images.enabled only allow images to be pulled that match the allowed patterns
--container-engine.name string set engine (allowed values: [containerd, docker, moby])
--diagnostics.show-muted unhide muted diagnostics
--experimental.virtual-machine.mount.9p.cache-mode string (allowed values: [none, loose, fscache, mmap])
--experimental.virtual-machine.mount.9p.msize-in-kib int maximum packet size
--experimental.virtual-machine.mount.9p.protocol-version string (allowed values: [9p2000, 9p2000.u, 9p2000.L])
--experimental.virtual-machine.mount.9p.security-model string (allowed values: [passthrough, mapped-xattr, mapped-file, none])
--experimental.virtual-machine.mount.type string how directories are shared (allowed values: [reverse-sshfs, 9p, virtiofs])
--experimental.virtual-machine.socket-vmnet use socket-vmnet instead of vde-vmnet
--experimental.virtual-machine.type string (allowed values: [qemu, vz])
--experimental.virtual-machine.use-rosetta
-h, --help help for start
--images.namespace string select only images from this namespace (containerd only)
--images.show-all show system images on Images page
--kubernetes.enabled run Kubernetes
--kubernetes.options.flannel use flannel networking; disable to install your own CNI
--kubernetes.options.traefik install and run traefik
--kubernetes.port int apiserver port
--kubernetes.version string choose which version of Kubernetes to run
--no-modal-dialogs avoid displaying dialog boxes
-p, --path string path to main executable
--port-forwarding.include-kubernetes-services show Kubernetes system services on Port Forwarding page
--virtual-machine.memory-in-gb int reserved RAM size
--virtual-machine.number-cpus int reserved number of CPUs

Global Flags:
--config-path string config file (default /Users/{username}/Library/Application Support/rancher-desktop/rd-engine.json)
--host string default is localhost; most useful for WSL
--password string overrides the password setting in the config file
--port string overrides the port setting in the config file
--user string overrides the user setting in the config file

Example:

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

rdctl version

Run rdctl version to see the current rdctl CLI version.

Example Output
> rdctl version
rdctl client version: 1.1.0, targeting server version: v1