Description
What would you like to be added?
I want commands of etcdctl to be organized and documented in a better way.
- For organizing i suggest to remove nested part of commands for example instead of having this:
user add Adds a new user
user delete Deletes a user
user get Gets detailed information of a user
user grant-role Grants a role to a user
user list Lists all users
user passwd Changes password of user
user revoke-role Revokes a role from a user
We can do something like this:
Basic KV commands:
del Removes the specified key or range of keys [key, range_end)
get Gets the key or a range of keys
put Puts the given key into the store
Management Commands:
user User related commands
role Role related commands
And rest of this for other commands.
- For documenting i suggest to make the documents and help texts for commands better and more helpful throw some examples and define better.
For example when we invokeetcdctl leahe -hwe get
NAME:
lease - Lease related commands
USAGE:
etcdctl lease <subcommand> [flags]
Maybe we can do something like this:
NAME:
lease - Lease related commands
Description:
Leases in etcd act as timers for data, automatically deleting keys when their associated lease expires.
USAGE:
etcdctl lease <subcommand> [flags]
etcdctl lease grant 60 # Creates a lease that lasts 60 seconds
etcdctl lease keep-alive <lease_id> --once # Resets the keep-alive time to its original value and cobrautl.Exits immediately
Add a one line description so new users can understand what it is without going and searching for what is the lease, it's a tradeoff we don't want to throw the whole document here just a little sip of what is it.
And put some popular usages in the USAGE section would be nice too.
Why is this needed?
As a newcomer to etcdctl it was hard for me to understand what it does at first, i was constantly searching the websites for commands to understand some of it. To enhance user experience, I propose implementing measures to clarify command functionalities upfront, easing the learning curve.
Also i think the first view of etcdctl -h is a little bit crowded and i believe with removing some subcommands that are not necessarry to show at first and style it a little bit this way users are greeted with a more intuitive interface.