rpc: help for commands #12864

<!-- This issue tracker is only for technical issues related to Bitcoin Core. General bitcoin questions and/or support requests are best directed to the Bitcoin StackExchange at https://bitcoin.stackexchange.com. For reporting security issues, please read instructions at https://bitcoincore.org/en/contact/. If the node is "stuck" during sync or giving "block checksum mismatch" errors, please ensure your hardware is stable by running memtest and observe CPU temperature with a load-test tool such as linpack before creating an issue! -->

<!-- Describe the issue -->

<!--- What behavior did you expect? -->

<!--- What was the actual behavior (provide screenshots if the issue is GUI-related)? -->

<!--- How reliably can you reproduce the issue, what are the steps to do so? -->

<!-- What version of Bitcoin Core are you using, where did you get it (website, self-compiled, etc)? -->

<!-- What type of machine are you observing the error on (OS/CPU and disk type)? -->

<!-- Any extra information that might be useful in the debugging process. -->

<!--- This is normally the contents of a `debug.log` or `config.log` file. Raw text or a link to a pastebin type site are preferred. -->

I find quite annoying that help rpc call returns ca 120 lines as a list of all commands. I don't remember exact form and arguments of bitcoin-cli commands so I need to re-check them quite often and always scroll in terminal. I suggest that help RPC call will be modified in the following way:

• bitcoin-cli help prints list of sections, i. e. Blockchain, Control, Generating, Mining, etc.
• bitcoin-cli help all prints list of all commands and sections like current bitcoin-cli help does
• bitcoin-cli help <section> prints list of commands from corresponding section
• bitcoin-cli help <command> will remain the same as in current implementation.

And I'm willing to do that if it appears to be desirable.

I don't think it's unusual for help text to fill more than one screen, and I can imagine an extra round trip being annoying for people who are just looking for a single command.

Does piping the output to less make this any less painful for you:

bitcoin-cli help | less

It's not that much painful, just a bit annoying. So I wondered whether people liked this idea. But when I think about it more, it's probably not desirable to introduce this unnecessary complexity into a code. I usually dedicate another whole window(s) to help(s) and man(s).

bitcoin-cli help prints list of sections, i. e. Blockchain, Control, Generating, Mining, etc.

NACK, this changes behaviour and I believe there are libraries parsing the output of this command (not that we should care but maybe we could avoid if not really necessary)

bitcoin-cli help <section> prints list of commands from corresponding section

Concept ACK, but you would have to know the section, not sure if very helpul.

IMO what would be useful is to partially match argument with the command table, like:

bitcoin-cli help raw

getrawmempool ( verbose )
combinerawtransaction ["hexstring",...]
createrawtransaction [{"txid":"id","vout":n},...] [{"address":amount},{"data":"hex"},...] ( locktime ) ( replaceable )
decoderawtransaction "hexstring" ( iswitness )
fundrawtransaction "hexstring" ( options iswitness )
getrawtransaction "txid" ( verbose "blockhash" )
sendrawtransaction "hexstring" ( allowhighfees )
signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )
signrawtransactionwithkey "hexstring" ["privatekey1",...] ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )
getrawchangeaddress ( "address_type" )
signrawtransactionwithwallet "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )

But that you can also get with | grep raw like @jnewbery suggests.

To be honest, I'd think we just need to tidy things up here. Check out geth help

https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options

@promag Is it worth creating a pull request to implement your partial match suggestion? I put together a simple patch here: https://github.com/razamobin/bitcoin/commit/496310c9f18c8cc300677f2faf5457fd0f326c5b

@razamobin feel free to submit it and see what other developers have to say.

I think this is very subjective. Personally I prefer the full list of commands on bitcoin-cli help, when I need a partial match I pipe it through grep.

It turns out my suggestion has problems. Calling bitcoin-cli -regtest signrawtransaction would give 3 matches:

signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )
signrawtransactionwithkey "hexstring" ["privatekey1",...] ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )
signrawtransactionwithwallet "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] sighashtype )

instead of signrawtransaction detailed help. You could argue if it's an exact match then it always shows the detailed help, but honestly just grep it.

Yeah, I ran into the same issue yesterday. I separated the logic so that exact match shows the detailed help as usual.

@razamobin are you planning to submit the PR? @jakubtrnka can this be closed?

I decided not to submit the PR based on feedback.

This seems very subjective, so I'm going to close for now.

Feel free to open a PR if you have a concrete proposal for a change. I expect it'd have difficulty being merged since most people seem fine with the way things are now.