search

gravitational / teleport

The easiest, and most secure way to access and protect all of your infrastructure.
https://goteleport.com
GNU Affero General Public License v3.0
17.6k stars 1.76k forks source link

Develop CLI Style guide #12811

Open klizhentas opened 2 years ago

klizhentas commented 2 years ago

Review Heroku CLI style guide and develop our own:

https://devcenter.heroku.com/articles/cli-style-guide

zmb3 commented 2 years ago

I would love to see some of the advice from https://seirdy.one/posts/2022/06/10/cli-best-practices/ incorporated.

zmb3 commented 2 years ago

Example of inconsistent use of --force flag: https://github.com/gravitational/teleport/issues/1872

Tener commented 2 years ago

I know this could be a large undertaking, but if we are looking into improving our CLI then I think considering the switch from kingpin to cobra is a worthwhile thing (https://github.com/spf13/cobra, https://cobra.dev/). I know things were different a few years back, but right now cobra sees much more activity: https://go.libhunt.com/compare-kingpin-vs-cobra.

Cobra generally looks more mature, better designed and more feature-rich (shell autocomplete, suggesting corrections on typos, ...).

zmb3 commented 2 years ago

Unlikely to happen as the tsh aliases work is being done on our fork of kingpin.

Tener commented 2 years ago

Unlikely to happen as the tsh aliases work is being done on our fork of kingpin.

I haven't tried it, but my gut feeling is that my tsh aliases PR wouldn't be substantially different with cobra: https://github.com/gravitational/teleport/pull/13305. (By the way: the PR is ready for review, so feel free to try it out.)

That being said, cobra is not a drop-in replacement, so some issues will likely appear in one place or another.

GavinFrazar commented 1 year ago

@smallinsky do you mind if I work on this? I think our CLI really needs refinement. It's the major entry-point to setting up and using Teleport, yet we have a lot of inconsistencies and issues with it. The first step in cleaning it up should be establishing our own rules around CLI code style and UX as this feature-request suggests. Then we can work to move our CLI into compliance with those rules, and then setting up lints and tests to keep us in compliance with the rules so we don't drift away from them as other work is done.

I've come across many more issues while working on https://github.com/gravitational/teleport/issues/19560 that make me think this should be prioritized.

edit: By "working on this" I mean to draft an RFD.

zmb3 commented 9 months ago

This should also include the use of colors, see #36929 for example.

GavinFrazar commented 9 months ago

This should also include the use of colors, see #36929 for example.

good point, also mentioned by https://seirdy.one/posts/2022/06/10/cli-best-practices/

Excessive animation and color can harm users with attention and/or vestibular disorders, and some on the autism spectrum. Many tools offer a --color[=WHEN] flag where WHEN is always, never, or auto. Expecting users to learn all the color configurations for all their tools is unrealistic; tools should respect the NO_COLOR environment variable.