chainlib/doc/texinfo/cli.texi

@node chainlib-cli

@section Command line interface provisions

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.

To use CLI provisions, @code{chainlib.cli} should be imported. This automatically imports the following submodules:

@table @code
@item arg
Define and/or select command-line arguments
@item config
Process configuration from command-line arguments and environment variables
@item rpc
Create RPC connection from configuration
@item wallet
Create wallet from configuration
@end table

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.


@subsection Arguments

@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.

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.

Following is a description of all pre-defined arguments that are available with @code{chainlib}.


@subsubsection -c, --config

Override configuration directives by reading ini-files in the given directory.

Only configuration directives defined in the schema may be overridden. @xref{chainlib-config}.


@subsubsection --env-prefix

Prepend the given string to configuration directives when overriding by environment variables

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.


@subsubsection --height

Query the chain RPC for results at a specific block height.

Applies to @emph{read} operations only.


@subsubsection -i, --chain-spec

Chain specification string for the blockchain connection.

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).

@subsubsection --fee-limit

Use the exact given fee multiplier to calculate the final bid to get transaction executed on the network.

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}.

If @emph{not} defined, the multiplier will be retrieved using the fees provider defined by the implementation.


@subsubsection --fee-price

Use the exact given fee price as factor to calculate bid to get transaction executed on the network.

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}.

If @emph{not} defined, the current recommended price will be retrieved from the fees provider defined by the implementation.


@subsubsection -n, --namespace

Append the given namespace to implicit configuration override paths.

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}.


@subsubsection --nonce

Start at the exact given nonce for the query.

If @emph{not} defined, the next nonce will be retrieved from the nonce provider defined by the implementation.


@subsubsection -p, --provider

URL of the chain RPC provider.


@subsubsection -s, --send

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.

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.


@subsubsection --seq

By default, a random RPC id will be generated for every RPC call.

However, some RPCs will only allow sequential serial numbers to be used as RPC ids, in which case this flag should be used.


@subsubsection --raw

Generate output suitable for passing to another command (e.g. UNIX pipes).


@subsubsection --rpc-auth

Tells the implementer which RPC authentication scheme to use (e.g. "basic" for http basic).


@subsubsection --rpc-credentials

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).

Credentials may for example also be a single value, like a private key, depending on the scheme and implementation.


@subsubsection --rpc-dialect

Tells the implementer to optimize query, result and error reporting for the specific chain RPC backend dialect.


@subsubsection -u, --unsafe

Allow arguments with blockchain addresses that are not checksum protected.


@subsubsection -v, -vv

Defines logging verbosity.

Specifically, @code{-v} will set loglevel to @code{INFO}, wheres @code{-vv} will set loglevel to @code{DEBUG}.

Default loglevel is up to the implementer, but it is advisable to keep it at @code{WARNING}.


@subsubsection -w, -ww

Toggles blocking in relation to chain RPC calls.

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. 

If @code{-ww} is set, the implementer should block to retrieve the results of @emph{all} of the preceding RPC transactions.

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.

If neither flag is set, the typical consequence is that the network transaction hash of the last transaction will be returned.


@subsubsection -y, --key-file

Read private key from the given key file.