cli: redesign proposal

[kradalby]

This pr is not to be merged, its end result is to serve as a "design doc" for how we organise our cli. Breaking changes allowed.

Comments, suggestions and proposals from humans in the community encouraged.

[kradalby]

I currently like this, where we split out the very much used node ones, but expiry is a bit weird because it also exist in different scopes.

Maybe only routes and tags?

[nblock]

auth is the authentication of nodes to headscale

Authentication of nodes and also SSH check.

headscale routes approve 12 "" # remove all from 12
headscale routes disapprove-all 12 # remove all from 12

An approve subcommand with an empty last target argument is confusing to some users. Because its unclear whether the user forgot the last argument or all routes should really be disapproved. We also have this now when using -r "". It came up a few times.

Maybe add a pair of subcommands to solve this in general? approve / disapprove or approve / no-approve and always require the last argument (in this case the route(s)).

headscale users set # optional fields are flags

I like the "optional fields as flags". Its flexible and can be extended as needed.

We will support outputting json, json-line and a human readable table. Default output mode is always the human
readable table. json formats will always show all data.

Do we even need json-line? If not, we could only provide json as universal machine readable output format and combine it with jsonpath somehow? Otherwise we'd have four formats:

• text (mangled by --column and --filter)
• json, json-line (mangled by --filter)
• json-path (arbitary data in json format)

expire vs. nodes expire

I like the "nodes expire" form better. Adding one more word to the argument list does not really matter but it imho
improves readability and discoverability:

• Which operations can I perform for a node/user/…: headscale nodes --help
• The target - in this case node needs to be supplied anyways. If there are more possible target groups, we'd need the distinction anyways. An example would be nodes and apikeys for expire: headscale expire node <...> / headscale expire apikeys <...>.

Other questions:

• Are global arguments kept as is? --config comes to mind.
• Are environment variables still supported as-is (HEADSCALE_CONFIG, …)

[nblock]

How should we do the formatting of the text output? Some columns are single valued (node name, user name) and some are lists (ip addresses, routes)? Should we keep it fixed (without stability guarantees) and direct users to jsonpath for script processing?

The text version should favor human readability and allow for some flexibility for upcoming changes (add, remove, reorder default columns). While its nice to use grep and friends to work with the CLI, there's json and jsonpath which is better suited for scripting.

The "one line per list entry" output is good for variable long lists such as routes. For the node's IP addresses its a bit hard to read as its almost always two lines which produces alternating rows and make it visually harder to read.

[ArcticLampyrid]

Do we even need json-line? If not, we could only provide json as universal machine readable output format and combine it with jsonpath somehow?

Perhaps we could omit the jsonpath option too. Providing only table and json formats is sufficient. When users require specific data extraction, they can handle it in the pipeline using tools such as jq. In modern IT operations, tools like jq are virtually always pre-installed.