Clarification and Improvement of `aut account import-private-key` Command Syntax

ravinayag commented 1 year ago

Description

Explain the new feature or suggested improvement in as much detail as you can. As a beginner, I found that the help text for the aut command assumes that the user should input the nodekey as shown below:

aut account import-private-key --keyfile nodekey

This command would result in an error. However, the correct command syntax may be: aut account import-private-key nodekey --keyfile my_private.key

The usage syntax is then reflect as: aut account import-private-key YOURKEYFILE --keyfile PRIVATE_KEY_FILE or aut account import-private-key YOURKEYFILE --keystore PRIVATE_KEY_FOLDER

AND the Explanation need to be.

**This command reads a plaintext key file (in hex) and creates a new encrypted private_key keystore file for it**.

Who are the expected users of the improvement? All beginners who are new to the project.

What is the impact of the improvement on the documentation website and its users? By providing clearer and more accurate help text, users will be able to run the commands more effectively, reducing potential confusion.

...

Rationale

Why should this improvement be made? Why is it worthwhile to develop and implement? The current syntax can be misleading or unclear, with the keyword "private key" causing confusion. Improving the command's help text will enhance user experience and reduce the likelihood of errors.

Ref :

$ aut account import-private-key --help
**Usage: aut account import-private-key [OPTIONS] PRIVATE_KEY_FILE**

  **Read a plaintext private key file (as hex), and create a new encrypted
  keystore file for it.**  Use - to read private key from stdin.  If no keyfile
  is specified, a default name is used (consistent with GETH keyfiles) in the
  keystore.

Implementation

Do you have ideas regarding the implementation of this feature? Updating the command's help text and usage syntax will assist users in following the correct input format.

Are you willing to implement this feature? Yes.

cmjc commented 1 year ago

Hi @ravinayag . Thank you for this feedback. Transferring the issue from docs.autonity.org to the aut repo as I think this is feedback about the aut tool.

If you think there is an issue with the docs page for import - https://docs.autonity.org/account-holders/create-acct/#import-account-using-aut - please raise another issue on that. Thanks!

aiman commented 1 year ago

@ravinayag Thanks for highlighting this issue with aut account import-private-key subcommand. I agree that the term PRIVATE_KEY_FILE in the can be confusing, because it can be easily confused with the encrypted private keyfile. Rather than tweaking the language, it seems better to just rename the subcommand to import-plaintext-key, and the positional argument can be renamed to PLAINTEXT_KEYFILE. This will be clearer hopefully.

autonity / aut