cli.texi (6232B)
1 @chapter Command line interface provisions 2 3 The base CLI provisions of @code{chainlib} simplifies the generation of a some base object instances by command line arguments, environment variables and configuration schemas. 4 5 To use CLI provisions, @code{chainlib.cli} should be imported. This automatically imports the following submodules: 6 7 @table @code 8 @item arg 9 Define and/or select command-line arguments 10 @item config 11 Process configuration from command-line arguments and environment variables 12 @item rpc 13 Create RPC connection from configuration 14 @item wallet 15 Create wallet from configuration 16 @end table 17 18 Any chain implementation building on @code{chainlib} should extend one or more of the classes in these modules as needed, for example order to add more configuration directives or command line argument flags. 19 20 21 @section Arguments 22 23 @code{chainlib} defines a set of arguments that are common concepts for interfacing with blockchain RPCs. Which arguments to use for a specific instantiation can be defined using flags or symbols that define groups of flags. 24 25 This functionality is provided by the @code{chainlib.cli.args.ArgumentParser} class. It is a thin wrapper around the standard library @code{argparser.ArgumentParser} class, only adding a method to add arguments to the instance based on the aforementioned flags. 26 27 Following is a description of all pre-defined arguments that are available with @code{chainlib}. 28 29 30 @subsection -c, --config 31 32 Override configuration directives by reading ini-files in the given directory. 33 34 Only configuration directives defined in the schema may be overridden. @xref{chainlib-config}. 35 36 37 @subsection --env-prefix 38 39 Prepend the given string to configuration directives when overriding by environment variables 40 41 Normally, if a configuration directive @code{FOO_BAR} exists, the environment variable @code{FOO_BAR} will override its value. If @code{--env-prefix BAZ} is passed, the environment variable @code{BAZ_FOO_BAR} will be used instead to override the configuration directive @code{FOO_BAR}. The environment variable @code{FOO_BAR} will in this case @emph{not} be used. 42 43 44 @subsection --height 45 46 Query the chain RPC for results at a specific block height. 47 48 Applies to @emph{read} operations only. 49 50 51 @subsection -i, --chain-spec 52 53 Chain specification string for the blockchain connection. 54 55 This informs the implementing code about the architecture and deployment of the blockchain network. It can also be relevant when creating signatures for the network (e.g. the EIP155 signature scheme for EVM). 56 57 @subsection --fee-limit 58 59 Use the exact given fee multiplier to calculate the final bid to get transaction executed on the network. 60 61 How the fee semantics are employed depend on the chain implementation, but the final resulting bid @emph{must always} be the product of @code{price * limit}. 62 63 If @emph{not} defined, the multiplier will be retrieved using the fees provider defined by the implementation. 64 65 66 @subsection --fee-price 67 68 Use the exact given fee price as factor to calculate bid to get transaction executed on the network. 69 70 How the fee semantics are employed depend on the chain implementation, but the final resulting bid @emph{must always} be the product of @code{price * limit}. 71 72 If @emph{not} defined, the current recommended price will be retrieved from the fees provider defined by the implementation. 73 74 75 @subsection -n, --namespace 76 77 Append the given namespace to implicit configuration override paths. 78 79 For example, if linux xdg-basedir path is used, a namespace argument of @code{foo} in implementation domain @code{bar} will result in the configuration override path @code{$HOME/.config/bar/foo}. 80 81 82 @subsection --nonce 83 84 Start at the exact given nonce for the query. 85 86 If @emph{not} defined, the next nonce will be retrieved from the nonce provider defined by the implementation. 87 88 89 @subsection -p, --provider 90 91 URL of the chain RPC provider. 92 93 94 @subsection -s, --send 95 96 CLI tools building on chainlib should @emph{never} submit to the network by default. Instead, resulting transactions ready for network submission should be output to terminal. 97 98 If the implementation wishes to allow the user to directly send to the network, the @code{-s} flag @emph{must} be used for this purpose. 99 100 101 @subsection --seq 102 103 By default, a random RPC id will be generated for every RPC call. 104 105 However, some RPCs will only allow sequential serial numbers to be used as RPC ids, in which case this flag should be used. 106 107 108 @subsection --raw 109 110 Generate output suitable for passing to another command (e.g. UNIX pipes). 111 112 113 @subsection --rpc-auth 114 115 Tells the implementer which RPC authentication scheme to use (e.g. "basic" for http basic). 116 117 118 @subsection --rpc-credentials 119 120 Tells the implemented wich RPC authentication credentials to use for selected rpc authentication scheme (e.g. "foo:bar" for user foo pass bar in scheme "basic" a.k.a. http basic). 121 122 Credentials may for example also be a single value, like a private key, depending on the scheme and implementation. 123 124 125 @subsection --rpc-dialect 126 127 Tells the implementer to optimize query, result and error reporting for the specific chain RPC backend dialect. 128 129 130 @subsection -u, --unsafe 131 132 Allow arguments with blockchain addresses that are not checksum protected. 133 134 135 @subsection -v, -vv 136 137 Defines logging verbosity. 138 139 Specifically, @code{-v} will set loglevel to @code{INFO}, wheres @code{-vv} will set loglevel to @code{DEBUG}. 140 141 Default loglevel is up to the implementer, but it is advisable to keep it at @code{WARNING}. 142 143 144 @subsection -w, -ww 145 146 Toggles blocking in relation to chain RPC calls. 147 148 If @code{-w} is set, the implementer should only block to obtain the result of the @emph{last, and as few as possible preceding} RPC transactions. 149 150 If @code{-ww} is set, the implementer should block to retrieve the results of @emph{all} of the preceding RPC transactions. 151 152 If the implementation consists of a single transaction, the effect of @code{-w} and @code{-ww} will always be the same. Nonetheless, the implementation will be forced to provide both arguments. 153 154 If neither flag is set, the typical consequence is that the network transaction hash of the last transaction will be returned. 155 156 157 @subsection -y, --key-file 158 159 Read private key from the given key file. 160 161 162