Proposal: change the API options in rdctl to look more like the fields in jq output

[ericpromislow]

Proposal to make the rdctl set and rdctl start options dealing with preference settings to use the JSON/jq syntax.

It's been awkward switching between the linux --snake-case-format and the json camelCase format, and I never liked seeing dozens of options when running help.

Commands:

rd set ( GLOBAL-FLAGS | SETTINGS ) ...

rdctl start( GLOBAL-FLAGS | SETTINGS )`

GLOBAL-FLAGS
      --config-path string  
      --password string  
      --port string
      --user string  

SETTINGS:

--set fullyQualified.camelCase.name=SCALAR
--set fullyQualified.camelCase.name SCALAR
--set-json another.fullyQualified.camelCase.name="['array', 'of', 'strings']"
--set-json another.fullyQualified.camelCase.name "['array', 'of', 'strings']"
--set-json yet.another.fQDN.name='{ field1: 3, field2: "string2" }'
--set-json yet.another.fQDN.name '{ field1: 3, field2: "string2" }'

This syntax is closer to the setting-syntax for helm install, with these differences:

There's no need for helm's --set-string or --set-literal. --set is used to set a scalar value, and --set-json is used to set a compound value.

Note that rdctl start retains --no-modal-dialogs and --path PATH-TO-EXECUTABLE

Migration

We can support both sets of options for version 11, with deprecation warnings when the old form is used, and drop support for the old form with version 12.

Future possibility:

If you're doing FQDN.field=VALUE you don't need to precede it with a --set. But if you want to leave out the = you need the --set option.

[mook-as]

I think using randomly uppercase things in CLIs are more frustrating than they are worth it; we should stick with the current syntax. I don't understand the issue with seeing the options in help, given that you'd normally never want help unless you need it; in the new scheme, it's not obvious how the user would know what options are available.

If anything, we should finally get around to fixing the command line parsing from the JS side to use the foo-bar syntax:
https://github.com/rancher-sandbox/rancher-desktop/blob/main/pkg/rancher-desktop/config/commandLineOptions.ts#L32

[ericpromislow]

OTOH, --set-json might not even be needed. I was playing with the rdctl set/start syntax to see if I could easily support settings compound values with JSON syntax, and it's straightforward to support it:

$ rdctl tester --container-engine.allowed-images.patterns=\
'["abc", "def"]'  --diagnostics.mutedChecks='{"field1": true, "field2": false}'
JSON buffer: {"version":9,""containerEngine":{"allowedImages":{"patterns":["abc","def"]}}, "diagnostics":{"mutedChecks":{"field1":true,"field2":false}}}

The caveat is that the user will need to use precise JSON syntax:

$ rdctl tester --container-engine.allowed-images.patterns='["abc", "def"
]' --diagnostics.mutedChecks='{"field1": true, field2: false}'
Error: invalid character 'f' looking for beginning of object key string

But it's better than what we have right now, which is requiring the user to fall back to the API, which also requires precise JSON

[ericpromislow]

Implementation notes...

But we run afoul with that golang omit_empty directive:

$ rdctl tester --container-engine.allowed-images.patterns='[]'
JSON buffer: {"version":9, "containerEngine":{"allowedImages":{}}}

This isn't a problem when using rdctl api /settings -X PUT because {... { "containerEngine":{"allowedImages": { "patterns": [] }}}} means clear the list of patterns, while {... { "containerEngine":{"allowedImages": { } } } } means don't change the list of patterns. By relying on the JSON marshaler

To deal with this:

In ServerSettingsForJSON change the following fields to pointers:

Application.Extensions.Allowed.List
Application.Extensions.Installed
ContainerEngine.AllowedImages.Patterns
Experimental.VirtualMachine.Proxy.Noproxy
WSL.Integrations
Diagnostics.MutedChecks

That solves the dropped-empty-compound-object problem.

[jandubois]

I think using randomly uppercase things in CLIs are more frustrating than they are worth it; we should stick with the current syntax.

That was my thought as well. But then we should use the same names inside the JSON too¹ because a user should never have to deal with both notations, as in

TOGGLE=$(rdctl api settings | jq '.experimental.virtualMachine.proxy.enabled|not')
rdctl set --experimental.virtual-machine.proxy.enabled=$TOGGLE

But if we use the kebab-style in JSON it makes jq awkward because you have to quote the symbols containing a dash:

jq '.experimental."virtual-machine".proxy.enabled'

Maybe that is acceptable. My "hard" requirement would be that users should only ever deal with one form of the option name. Which is why I'm willing to explore Eric's suggestion, even though I dislike having to use camelCase names with the CLI.

Footnotes

1. Only in the JSON blobs, obviously the names in TypeScript/JavaScript would still be camelCase, so we would need to transform on read/write. ↩