mte/unikernel/duniverse/cmdliner/doc/cli.mld

{0:cmdline Command line interface}

This manual describes how your tool ends up interacting
with shells when you use Cmdliner.

{1:invocation Tool invocation}

For tools evaluating a command without subcommands the most general
form of invocation is:

{v
tool [OPTION]… [ARG]…
v}

The tool automatically reponds to the [--help] option by printing
{{!help}the help}. If a version string is provided in the
{{!Cmdliner.Cmd.val-info}command information}, it also automatically
responds to the [--version] option by printing this string on standard
output.

Command line arguments are either {{!optargs}{e optional}} or
{{!posargs}{e positional}}. Both can be freely interleaved but since
[Cmdliner] accepts many optional forms this may result in
ambiguities. The special {{!posargs} token [--]} can be used to
resolve them: anything that follows it is treated as a positional
argument.

Tools evaluating commands with subcommands have this form of invocation

{v
tool [COMMAND]… [OPTION]… [ARG]…
v}

Commands automatically respond to the [--help] option by printing
{{!help}their help}. The sequence of [COMMAND] strings must be the first
strings following the tool name – as soon as an optional argument is
seen the search for a subcommand stops.

{1:args Arguments}

{2:optargs Optional arguments}

An optional argument is specified on the command line by a {e name}
possibly followed by a {e value}.

The name of an option can be short or long.

{ul
{- A {e short} name is a dash followed by a single alphanumeric
   character: [-h], [-q], [-I].}
{- A {e long} name is two dashes followed by alphanumeric
   characters and dashes: [--help], [--silent], [--ignore-case].}}

More than one name may refer to the same optional argument.  For
example in a given program the names [-q], [--quiet] and [--silent]
may all stand for the same boolean argument indicating the program to
be quiet.

The value of an option can be specified in three different ways.

{ul
{- As the next token on the command line: [-o a.out], [--output a.out].}
{- Glued to a short name: [-oa.out].}
{- Glued to a long name after an equal character: [--output=a.out].}}

Glued forms are especially useful if the value itself starts with a
dash as is the case for negative numbers, [--min=-10].

An optional argument without a value is either a {e flag} (see
{!Cmdliner.Arg.flag}, {!Cmdliner.Arg.vflag}) or an optional argument with
an optional value (see the [~vopt] argument of {!Cmdliner.Arg.opt}).

Short flags can be grouped together to share a single dash and the
group can end with a short option. For example assuming [-v] and
[-x] are flags and [-f] is a short option:

{ul
{- [-vx] will be parsed as [-v -x].}
{- [-vxfopt] will be parsed as [-v -x -fopt].}
{- [-vxf opt] will be parsed as [-v -x -fopt].}
{- [-fvx] will be parsed as [-f=vx].}}

{2:posargs Positional arguments}

Positional arguments are tokens on the command line that are not
option names and are not the value of an optional argument. They are
numbered from left to right starting with zero.

Since positional arguments may be mistaken as the optional value of an
optional argument or they may need to look like option names, anything
that follows the special token ["--"] on the command line is
considered to be a positional argument:

{v
tool --option -- but --now we -are --all positional --argu=ments
v}

{2:constraints Constraints on option names}

Using the cmdliner library puts the following constraints on your
command line interface:

{ul
{- The option names [--cmdliner] and [--__complete] are reserved by the
   library.}
{- The option name [--help], (and [--version] if you specify a version
   string) is reserved by the library. Using it as a term or option
   name may result in undefined behaviour.}
{- Defining the same option or command name via two different
   arguments or terms is illegal and raises [Invalid_argument].}}

{1:envlookup Environment variables}

Non-required command line arguments can be backed up by an environment
variable.  If the argument is absent from the command line and
the environment variable is defined, its value is parsed using the
argument converter and defines the value of the argument.

For {!Cmdliner.Arg.flag} and {!Cmdliner.Arg.flag_all} that do not have an
argument converter a boolean is parsed from the lowercased variable value
as follows:

{ul
{- [""], ["false"], ["no"], ["n"] or ["0"] is [false].}
{- ["true"], ["yes"], ["y"] or ["1"] is [true].}
{- Any other string is an error.}}

Note that environment variables are not supported for
{!Cmdliner.Arg.vflag} and {!Cmdliner.Arg.vflag_all}.

{1:help Help and man pages}

Help and man pages are are generated when you call your tool or a subcommand
with [--help]. By default, if the [TERM] environment variable
is not [dumb] or unset, the tool tries to {{!paging}page} the manual
so that you can directly search it. Otherwise it outputs the manual
as plain text.

Alternative help formats can be specified with the optional argument
of [--help], see your own [tool --help] for more information.

{@sh[
tool --help
tool cmd --help
tool --help=groff > tool.1
]}

{2:paging Paging}

The pager is selected by looking up, in order:

{ol
{- The [MANPAGER] variable.}
{- The [PAGER] variable.}
{- The tool [less].}
{- The tool [more].}}

Regardless of the pager, it is invoked with [LESS=FRX] set in the
environment unless, the [LESS] environment variable is set in your
environment.

{2:install_tool_manpages Install}

The manpages of a tool and its subcommands can be installed to a root
[man] directory [$MANDIR] by invoking:

{@shell[
cmdliner install tool-manpages thetool $MANDIR
]}

This looks up [thetool] in the [PATH]. Use an explicit file path like
[./thetool] to directly specify an executable.

If you are also {{!install_tool_completion}installing completions}
rather use the [install tool-support] command, see this
{{!page-cookbook.tip_tool_support}cookbook tip} which also has
instructions on how to install if you are using [opam].

{1:cli_completion Command line completion}

Cmdliner programs automatically get support for shell command line
completion.

The completion process happens via a {{!completion_protocol}protocol}
which is interpreted by generic shell completion scripts that are
installed by the library. For now the [zsh] and [bash] shells are
supported.

Tool developers can easily {{!install_tool_completion}install}
completion definitions that invoke these completion scripts. Tool
end-users need to {{!user_configuration}make sure} these definitions are
looked up by their shell.

{2:user_configuration End-user configuration}

If you are the user of a cmdliner based tool, the following
shell-dependent steps need to be performed in order to benefit from
command line completion.

{3:user_zsh For [zsh]}

The [FPATH] environment variable must be setup to include the
directory where the generic cmdliner completion function is
{{!install_completion} installed} {b before} properly initializing the
completion system.

For example, {{:https://github.com/ocaml/opam/issues/6427}for now}, if
you are using [opam]. You should add something like this to your
[.zshrc]:

{@sh[
FPATH="$(opam var share)/zsh/site-functions:${FPATH}"
autoload -Uz compinit
compinit -u
]}

Also make sure this {b happens before} [opam]'s [zsh] init script
inclusion, see {{:https://github.com/ocaml/opam/issues/6428}this
issue}. Note that these instruction do not react dynamically
to [opam] switches changes so you may see odd completion behaviours
when you do so, see this {{:https://github.com/ocaml/opam/issues/6427}this
opam issue}.

After this, to test everything is right, check that the [_cmdliner_generic]
function can be looked by invoking it (this will result in an error).

{@sh[
> autoload _cmdliner_generic
> _cmdliner_generic
_cmdliner_generic:1: words: assignment to invalid subscript range
]}

If the function cannnot be found make sure the [cmdliner] library is
installed, that the generic scripts were
{{!install_generic_completion}installed} and that the
[_cmdliner_generic] file can be found in one of the directories
mentioned in the [FPATH] variable.

With this setup, if you are using a cmdliner based tool named
[thetool] that did not {{!install_tool_completion}install} a completion
definition. You can always do it yourself by invoking:

{@sh[
autoload _cmdliner_generic
compdef _cmdliner_generic thetool
]}

{3:user_bash For [bash]}

These instructions assume that you have
{{:https://repology.org/project/bash-completion/versions}[bash-completion]}
installed and setup in some way in your [.bashrc].

The [XDG_DATA_DIRS] environment variable must be setup to include the
[share] directory where the generic cmdliner completion function is
{{!install_completion}installed}.

For example, {{:https://github.com/ocaml/opam/issues/6427}for now}, if
you are using [opam]. You should add something like this to your
[.bashrc]:
{@sh[
XDG_DATA_DIRS="$(opam var share):${XDG_DATA_DIRS}"
]}

Note that these instruction do not react dynamically to [opam]
switches changes so you may see odd completion behaviours when you do
so, see this {{:https://github.com/ocaml/opam/issues/6427}this opam
issue}.

After this, to test everything is right, check that the [_cmdliner_generic]
function can be looked up:

{@sh[
> _completion_loader _cmdliner_generic
> declare -F _cmdliner_generic &>/dev/null && echo "Found" || echo "Not found"
Found!
]}

If the function cannot be found make sure the [cmdliner] library is
installed, that the generic scripts were
{{!install_generic_completion}installed} and that the
[_cmdliner_generic] file can be looked up by [_completion_loader].

With this setup, if you are using a cmdliner based tool named
[thetool] that did not {{!install_tool_completion}install} a completion
definition. You can always do it yourself by invoking:

{@sh[
_completion_loader _cmdliner_generic
complete -F _cmdliner_generic thetool
]}

{b Note.} {{:https://github.com/scop/bash-completion/commit/9efc596735c4509001178f0cf28e02f66d1f7703}It seems} [_completion_loader] was deprecated in
bash-completion [2.12] in favour of [_comp_load] but many distributions
are on [< 2.12] and in [2.12] [_completion_loader] simply calls
[_comp_load].

{2:install_completion Install}

Completion scripts need to be installed in subdirectories of a
{{:https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html}[share]}
directory which we denote by the [$SHAREDIR] variable below. In a
package installation script this variable is typically defined by:

{@sh[
SHAREDIR="$DESTDIR/$PREFIX/share"
]}

The final destination directory in [share] depends on the shell:

{ul
{- For [zsh] it is [$SHAREDIR/zsh/site-functions]}
{- For [bash] it is [$SHAREDIR/bash-completion/completions]}}

If that is unsatisfying you can output the completion scripts directly
where you want with the [cmdliner generic-completion] and
[cmdliner tool-completion] commands.

{3:install_generic_completion Generic completion scripts}

The generic completion scripts must be installed by the
[cmdliner] library. They should not be part of your tool install.  If
they are not installed you can inspect and install them with the
following invocations, invoke with [--help] for more information.

{@sh[
cmdliner generic-completion zsh   # Output generic zsh script on stdout
cmdliner install generic-completion $SHAREDIR             # All shells
cmdliner install generic-completion --shell zsh $SHAREDIR # Only zsh
]}

Directories are created as needed. Use option [--dry-run] to see which
paths would be written by an [install] invocation.

{3:install_tool_completion Tool completion scripts}

If your tool named [thetool] uses Cmdliner you should install completion
definitions for them. They rely on the {{!install_generic_completion}generic
scripts} to be installed. These tool specific scripts can be inspected
and installed via these invocations:

{@sh[
cmdliner tool-completion zsh thetool  # Output tool zsh script on stdout.
cmdliner install tool-completion thetool $SHAREDIR             # All shells
cmdliner install tool-completion --shell zsh thetool $SHAREDIR # Only zsh
]}

Directories are created as needed. Use option [--dry-run] to see which
paths would be written by an [install] invocation.

If you are also {{!install_tool_manpages}installing manpages} rather
use the [install tool-support] command, see this
{{!page-cookbook.tip_tool_support}cookbook tip} which also has
instructions on how to install if you are using [opam].

{2:completion_protocol Completion protocol}

There is no standard that allows tools and shells to interact to
perform shell command line completion. Completion is supposed to
happen through idiosyncratic, ad-hoc, obscure and brain damaging
shell-specific completion scripts.

To alleviate this, Cmdliner defines one generic script per shell and
interacts with it using the protocol described below. The protocol can
be used to implement generic completion scripts for other shells. The
protocol is versioned but can change even between minor versions of
Cmdliner. Generic scripts for popular shells can be inspected via
the [cmdliner generic-completion] command.

The protocol betwen the shell completion {e script} and a
cmdliner based {e tool} is as follows:

{ol
{- When completion is requested the script invokes the tool with a
   modified command line:
   {ul
   {- The first argument to the tool ([Sys.argv.(1)]) must be the
       option [--__complete].}
   {- The (possibly empty) argument [ARG] on which the completion is
      requested must be replaced by {e exactly} [--__complete=ARG]. Note
      that this can happen after the [--] token, this is the reason
      why we have an explicit [--__complete] argument in [Sys.argv.(1)]:
      it indicates the command line parser must operate in a special mode.}}}
{- The tool responds by writing on standard output a list of
   completion directives which match the [completions] rule of the grammar
   given below.}
{- The script interprets the completion directives according
   to the given semantics below so that the shell can display the
   completions. The script is free to ignore directives
   or data that it is unable to present.}}

The following ABNF grammar is described using the notations of
{{:https://www.rfc-editor.org/rfc/rfc5234}RFC 5234} and
{{:https://www.rfc-editor.org/rfc/rfc7405}RFC 7405}. A few constraints
are not expressed by the grammar:

{ul
{- Except in the [completion] rule, the byte stream may contain ANSI escape
   sequences introduced by the byte [0x1B].}
{- After stripping the ANSI escape sequences, the resulting byte stream must
   be valid UTF-8 text.}}

{@abnf[
completions = version nl directives
version = "1"
directives = *(directive nl)
directive = message / group / %s"files" / %s"dirs" / %"restart"
message = %s"message" nl text nl %s"message-end"
group = %s"group" nl group_name nl *item
group_name = *pchar
item = %s"item" nl completion nl item_doc nl %s"item-end"
completion = *pchar
item_doc = text
text = *(pchar / nl)
nl = %0A
pchar = %20-%7E / %8A-%FF
]}

The semantics of directives is as follows:

{ul
{- A [message] directive defines a message to be reported to the user.
   It is multi-line ANSI styled text which cannot have a line that is
   exactly made of the text [message-end] as it is used to signal the
   end of the message. Messages should be reported in the order they
   are received.}
{- A [group] directive defines an informational [group_name] followed
   by a possibly empty list of completion items that are part of the
   group. An item provides a [completion] value, this is a string that
   defines what the requested [ARG] value can be replaced with. It is
   followed by an [item_doc], multi-line ANSI styled text which cannot
   have a line that is exactly made of the text [item-end] as it is
   used to signal the end of the item.}
{- A [file] directive indicates that the script should add existing
   files staring with [ARG] to completion values.}
{- A [dir] directive indicates that the script should add existing
   directories starting with [ARG] to completion values.}
{- A [restart] directive indicates that the script should restart
   shell completion as if the command line was starting after the leftmost
   [--] disambiguation token. The directive never gets emited if
   there is no [--] on the command line.}}

You can easily inspect the completions of any cmdliner based tool by
invoking it like the protocol suggests. For example for the [cmdliner]
tool itself:

{@shell[
cmdliner --__complete --__complete=
]}

{1:error_message_styling Error message ANSI styling}

Since Cmdliner 2.0 error messages printed on [stderr] use styled text
with ANSI escapes unless one of the following conditions is met:

{ul
{- The [NO_COLOR] environment variable is set and different
   from the empty string. Yes, even if you have [NO_COLOR=false], that's
   what the particularly dumb {:https://no-color.org} standard says.}
{- The [TERM] environment variable is [dumb].}
{- The [TERM] environment variable is unset and {!Sys.backend_type} is
   not [Other "js_of_ocaml"]. Yes, browser consoles support
   ANSI escapes. Yes, you can run Cmdliner in your browser.}}

{1:legacy_prefix_specification Legacy prefix specification}

Before Cmdliner 2.0, command names, long option names and
{!Cmdliner.Arg.enum} values could be specified by a prefix as long as
the prefix was not ambiguous.

This turned out to be a mistake. It makes the user experience of the
tool unstable as it evolves: former user established shortcuts or
invocations in scripts may be broken by new command, option and
enumerant additions.

Therefore this behaviour was unconditionally removed in Cmdliner
2.0. If you happen to have scripts that rely on it, you can invoke
them with [CMDLINER_LEGACY_PREFIXES=true] set in the environment to
recover the old behaviour. {b However the scripts should be fixed: this
escape hatch will be removed in the future.}

The [CMDLINER_LEGACY_PREFIX=true] escape hatch should not be used for
interactive tool interaction. In particular the behaviour of Cmdliner
completion support under this setting is undefined.