Alternative CLI ideas

[errordeveloper]

For me it would be more intuitive if the CLI was done in a kind of a CRUD style.

Something similar to the following:

fluxctl define-service <service> <IP address>:<port>[/tcp|http]
fluxctl update-service <service> <IP address>:<port>[/tcp|http]
fluxctl revoke-service <service>
fluxctl show-service <service>
fluxctl list-services
fluxctl define-selector <service> <rule> <address spec> [<selector>...]
fluxctl update-selector <service> <rule> <address spec> [<selector>...]
fluxctl revoke-selectors <service>
fluxctl list-selectors <service>

...or, perhaps somewhere in between the above and what it currently looks like. The point being is that it's unclear what sort of action each of the given commands performs, unless the user read the manual and the concepts are simple enough to encode within the actual commands.

[errordeveloper]

Also, I find named flag more user friendly than lists of arguments with special syntax at some positions in those lists. Actually, I can see a bug in the current documentation, which leads to me to think that might be the direction already - the toplevel usage summary shows <IP address>:<port>[/tcp|http], while the examples says 10.128.0.1:80 --protocol http instead.

I'd turn this:

<service> <IP address>:<port>[/tcp|http]

into:

--service-name=<service> --addr=<IP address> --port=<port> [--protocol=tcp|http]

Actually, may be the first argument could represent the action and then the current example with

fluxctl service search-svc 10.128.0.1:80 --protocol http
fluxctl select search-svc default --port-mapped 8080 --image searchapi

can be turned into a single command similar to this:

fluxctl define \
  --service-name=search-svc --addr=10.128.0.1 --port=80 --protocol=http \
  --rule=default --map-port=8080 --container-image=searchapi

or split into two commands like this:

fluxctl define --service-name=search-svc --addr=10.128.0.1 --port=80 --protocol=http
fluxctl update --service-name=search-svc --rule=default --map-port=8080 --container-image=searchapi

And fluxctl show could potentially take any information know about service or selector, e.g.:

fluxctl show --service-name=search-svc
fluxctl show --service-name="*" # or which may be the default
fluxctl show --container-image="weaveworks/*"
fluxctl show --container-label=<expr>
fluxctl show --port=80

[errordeveloper]

I can completely understand reason for the current design, and I do hugely appreciate the way it is, but I just though I might give a fresh view on how it may be streamlined. The above might look quite dried out potentially over-generalised, but at the same time time that seems rather practical to me.

[squaremo]

All good food for thought, thanks Ilya.

Arguments v options (flags)

I have been following the Unix style of arguments being mandatory, and options being optional -- thus, when the address was no longer mandatory, it became an option. But the service name is not (usually) optional, so it's an argument.

I appreciate the idea that flags are like keyword arguments, though -- certainly I would like as few arguments as possible, and in as predictable positions as possible. The rule name in fluxctl select service rule ... could be optional for instance (we can generate and return it, since most of the time the user won't care what its name is). Which pretty much leaves the service name, almost always present as an argument.

Address format

It's necessary to provide both an IP address and port, or neither -- so I think it's reasonable to jam them together in one option. The protocol is another matter -- it should probably be only an option. (I added it into the address format as a convenience, but it's not much of one ..)

Namespaces for commands

While we have just a handful of verbs, I think it's OK to keep them at the top level of subcommands (fluxctl select ..., fluxctl query ...). There is little if any ambiguity to what they will do; except, perhaps, list and query. Adding namespaces mostly just makes the commands longer, while this is the case.

We may need room to grow, though. It's not clear to me which nouns the verbs would attach to -- do you fluxctl instances select, fluxctl service select, or fluxctl selection create? (There's no meaning to a selection outside of it selecting instances of a service, so probably not the last, at least).