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):
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\
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
> 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.
Details
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.
Details
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>
Details
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>
Details
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
Details
Example Output
Example
$ rdctl extension ls
Extension IDs
docker/logs-explorer-extension:0.2.2