The clic
library#
tezos-clic is an OCaml combinator library for writing
self-documenting command-line argument parsers. Clic is similar to
cmdliner, but (unlike cmdliner)
tezos-clic
allows to define a domain-specific
language as a subset of a natural language, by mixing keyword and
positional arguments. For example, in octez-client
, commands look
like this, thanks to tezos-clic
:
octez-client list understood protocols
octez-client compute chain id from block hash <hash>
octez-client originate contract <contract_alias> transferring <initial_balance> from <originator> running <script>
clic
is used for most of the binaries distributed with Octez, such
as octez-client
and octez-codec
. A notable exception is
octez-node
which uses cmdliner
.
In this tutorial, we will give a gentle introduction to clic
by
demonstrating how to implement a wallet command inspired by those of
octez-client
. Impatient readers will find the full example
in this file.
Wallet example#
Command-line parsing in clic
is centered around commands. A command
roughly corresponds to one action of the command-line application. For
instance, octez-client get balance
and octez-client run script
<script>
are two different commands.
To demonstrate the use of clic
, we will add the following command to a dummy octez-client: list
known contracts
. As the name indicates, this command outputs
the contracts known to the wallet.
Commands execute in a user-supplied context. Typically, the context serves as an abstraction barrier between the command and its execution environment. This mechanism allows commands to be defined once, but reused in different contexts. An example where this useful is for swapping out the normal context for a dry-run context, allowing users to simulate the effect of commands before running them for real.
Note that using contexts is not required: it can be side-stepped by
defining commands that execute over a
context of type unit
.
In the running example, we define a context whose job is to contain the actual implementation of the commands.
We first declare CONTEXT
as the signature of modules that contain a
list_known_contracts
function. As we add more commands to the
example, we will also extend the context. For convenience, we add a
type alias context
for first-class CONTEXT
modules.
module type CONTEXT = sig
val list_known_contracts : unit -> unit
end
type context = (module CONTEXT)
We define a Dummy_context
that satisfies
the CONTEXT
signature, with a place-holder function simply printing
what the actual function would do.
module Dummy_context : CONTEXT = struct
let list_known_contracts () =
Format.printf "<Print the list of known contracts>\n"
end
Commands are defined through the Tezos_clic.command
function. It has the following signature:
Tezos_clic.command :
?group:Tezos_clic.group ->
desc:string ->
('b, 'ctx) Tezos_clic.options ->
('a, 'ctx) Tezos_clic.params ->
('b -> 'a) -> 'ctx Tezos_clic.command
First, commands have a group and description that are used to
generate documentation.
Groups are used to organize commands of related functionality. This is
convenient for applications such as octez-client
that defines a
large number of commands which are grouped on themes such as
querying, testing, and address management. You can see the documentation
online.
In our example, using groups is not required, but we add a group to demonstrate the feature. A group is just a name and a description of the commands in that group.
let wallet_group =
{Tezos_clic.name = "wallet_group"; title = "Wallet-related commands"}
The third argument to Tezos_clic.command
specifies the set of options
that commands take, which modulate its behavior (think --verbose
or --output json
). The value of the options will be collected as a
value of type 'b
.
The command is specified through a sequence of params, given as the
fourth argument to Tezos_clic.command
. Params can be prefixes: fixed
strings that must be given when calling the command. Above, we
mentioned the get balance
command of octez-client
. The
sequence get balance
is an example of such a prefix. A param can
also define a hole to be filled by the user on the command line. An example is given by
octez-client get balance for <contract>
. Here, the command
consists of a sequence of prefixes get balance for
followed by the
hole <contract>
, filled by the user on the command-line. No matter how the params
specification is constructed, it is terminated by the combinator Tezos_clic.stop
.
The params specification will construct a function type 'a
, which together
with the type 'b
from the options is
used to construct the signature 'b -> 'a
that the command
handler must adhere
to.
Note also that by construction, the type 'a
will always be of
the form ... -> 'ctx -> unit tzresult Lwt.t
, so that commands
always receive a context and must return unit
in the tzresult Lwt.t
monad.
The fifth argument Tezos_clic.command
is the command handler. This
function implements the actual command. It is passed any supplied
command-line options (as a value of type 'b
) and the contents of
any holes in the params (which are, respectively, types of the
arguments of the function type 'a
).
An example will be helpful to illustrate the signature of the command handler.
A command
that takes no options will have 'b = unit
. If, furthermore, its
params have no holes, then 'a = context -> unit tzresult Lwt.t
. The
command is thus a function
unit -> context -> unit tzresult Lwt.t
In other words, taking no arguments except for ()
and the context, and
returning unit
wrapped in the tzresult
and Lwt.t
monads.
As a second illustration of the signature of the command handler,
consider a command get balance for <contract>
, where <contract>
is of type Contract.t
.
Additionally, the command should
consume a --output <format>
option (where <format>
is a string
such as "json"
, "csv"
, etc.). In this case, 'b = string option
,
'a = Contract.t -> context -> unit tzresult Lwt.t
, and the command
handler a function with the signature:
string option -> Contract.t -> context -> unit tzresult Lwt.t
We now have enough meat on our bones to define the list known contracts
command.
module List_known_contracts = struct
let options = Tezos_clic.no_options
let params = Tezos_clic.(prefixes ["list"; "known"; "contracts"] stop)
let list_known_contracts_handler :
unit -> context -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t =
fun () ctxt ->
let module C = (val ctxt) in
C.list_known_contracts () ;
Lwt_result_syntax.return_unit
let command =
Tezos_clic.command
~group:wallet_group
~desc:"Prints the list of known contracts"
options
params
list_known_contracts_handler
end
let commands = [List_known_contracts.command]
We wrap the command and its related definitions in a module
List_known_contracts
. We specify that the command should have no
options through Tezos_clic.no_options
. We specify that the params is
a list of prefixes without holes. We then define the command
handler list_known_contracts_handler
. As the command has no
options and its params no holes, the signature of the handler becomes:
unit -> context -> unit tzresult Lwt.t
This command handler does no more than unwrap and call the appropriate function of the
context. Finally we add the command to the full list of commands
commands
that the application will provide.
Having thus defined the commands, we now define the entrypoint of our application:
let () =
(* 1. Setup formatter with color *)
ignore
Tezos_clic.(
setup_formatter
Format.std_formatter
(if Unix.isatty Unix.stdout then Ansi else Plain)
Short) ;
(* 2. Setup context and dispatch commands *)
let ctxt = (module Dummy_context : CONTEXT) in
let result =
Lwt_main.run
(Tezos_clic.dispatch commands ctxt (Array.to_list Sys.argv |> List.tl))
in
(* 3. Handle results *)
match result with
| Ok () -> ()
| Error [Tezos_clic.Help _command] ->
Format.printf "<display help>\n" ;
exit 0
| Error _ ->
Format.printf "Could not parse command-line arguments.\n" ;
exit 1
It consists of three sections. We first setup a formatter that
depending on whether the command is executed in a tty (as opposed to
e.g. being piped to a file) enables color in the output. Then, we
pack our context in a first-class module, that we pass to the
Tezos_clic.dispatch
. This function takes the full list of commands, as
defined by commands
, the context, and the list of raw command-line
arguments passed through the application. The list of command-line
arguments should not contain the first element (the name of the
program itself), so this is why the List.tl
function is used. The dispatch
function will parse the arguments,
and call the appropriate command handler if a valid command was
given. If this is the case, Ok ()
is returned. If no arguments
have been passed, or if --help
is given, then Error [Tezos_clic.Help
_command]
is returned. In this case the application should print the appropriate
usage instruction. If some other unrecognized
arguments are given we give a placeholder error message, which we’ll
replace with something more helpful below.
We use dune
to compile the example, with the following dune
file:
(executable
(name clic_example)
(libraries
octez-libs.clic
lwt.unix))
The dependencies of the example are tezos-clic
and lwt.unix
which can be installed through opam install tezos-clic lwt
. Let’s
try it out:
$ dune exec ./clic_example.exe -- list known contracts
<Print the list of known contracts>
which is as expected. Giving no
arguments, or when passed the --help
flags, our placeholder help
message is output:
$ dune exec ./clic_example.exe -- --help
<display help>
$ dune exec ./clic_example.exe --
<display help>
Similarly, if we attempt to call an unrecognized command:
$ dune exec ./clic_example.exe -- foobar
Could not parse command-line arguments.
Conclusion#
This example demonstrates how to define a simple clic
application
with one simple command. This is far from a complete demonstration of
clic
. clic
also includes facilities for generating
interactive, searchable documentation, with both command-line and HTML
outputs. clic
also gives facilities for implementing shell
auto-completion. For more information, refer to clic
's
API documentation .