cliapp - config file and option conventions for Python command line framework
is a Python programming framework for writing command line
applications for Unix-like operating systems. This manual page describes the
conventions for configuration files and command line parsing provided by
Configuration file variables
and command line options
under a uniform abstraction: every setting is available both
in configuration files and command line options. There are a few settings,
provided by the framework itself, which are only available on the command
line. For example, --help
outputs a short help text, listing all the
available options, and --dump-config
outputs a list of current
Command line parsing
follows GNU conventions: short options start with a
single dash, long options with two dashes, and options may be used anywhere on
the command line. The order of options versus non-options does not matter. The
exception is some of the options provided by the framework, which are executed
immediately when found, and may be prevent the rest of the options from being
is one of these, so use it at the end of the
command line only.) Use --
on the command line to signal the end of
options: no arguments after that are considered to be option.
Some settings may have aliases, which can be only a single character, and in
that case they're parsed as single-character option names.
Some applications have subcommands
, which means that the first non-option
argument is used to tell the application what to do. This is similar to what
many version control systems do, for example CVS, svn, bzr, and git. Options
are global, and are not specific to subcommands. Thus, --foo
same thing, regardless of what subcommand is being used.
Configuration files use INI or YAML file syntax. Files named
are in YAML syntax. Everything else are in INI syntax.
An INI file might look like this:
foo = bar
yo = yoyo
The same file in YAML syntax would be:
All the settings are in the [config]
section. Other sections are allowed,
but it is up to the application to give meaning to them.
Multiple configuration files may be read. Settings from later ones override
settings from earlier ones. Options override settings from the configuration
Some settings may be a list of values (each value being a string). For example,
there might be a setting for patterns to search for, and multiple patterns are
allowed. On the command line, that happens by using the option multiple times.
In the configuration file, all values are given on one logical line, separated
This is a non-standard extension to the INI file syntax.
To include an item that itself contains a comma, surround the item with double
quotes. There is no way to escape double quotes.
pattern = foo, bar, foobar, "hello, world"
Note than in versions of cliapp prior to 1.20150829, the command line option
would also break values with commas. This has since been fixed.
Configuration files in YAML use standard YAML syntax to express lists.
Some options take a value that gives the size as bytes. These take an optional
unit suffix. A plain integer is the size in bytes. The following units are
Suffixes may be upper or lower case, without change in meaning. Note that
"b" and "B" are identical, and both mean byte, not bit.
When a setting can be either on or off, it's called a Boolean setting. Such
settings are turned off by default, and turned on if used on the command line.
In a configuration file, they need to be set to a value: if the value is one
, or the number 1, the setting is turned
on. Any other value means it is turned off.
verbose = true
attack-kittens = no
This turns the verbose setting on, but does not launch attack kittens.
For every boolean setting, two command line options are added. If the setting is
, the option --foo
will turn the setting on, and
will turn it off. The negation is only usable on the command
line: its purpose is to allow the command line to override a setting from the
Programs using cliapp
automatically support several options for
configuring the Python logging
module. See the --help
options starting with log
for details. Logging can happen to a file or
the system log. Log files can be rotated automatically based on size.
option enables additional debug logging, which is usually
only useful for programmers. The option configures the tracing
for Python, by Lars Wirzenius, which allows logging values of variables and
other debug information in a way that is very lightweight when the tracing is
turned off. The option specifies for which source code files to turn on
tracing. The actual logging happens via the normal Python logging facilities,
at the debug level.
You can run the application under the Python profiler (cProfile
setting an environment variable. The name of the variable is
, where FOO
is the name of the program, as set by the
application code or determined by cliapp
automatically. The value of
the environment variable is the name of the file to which the resulting
profile is to be written.
can generate parts of a manual page: the SYNOPSIS
sections. It fills these in automatically based on the
subcommand and settings that a program supports. Use the
=FILE option, which is added
automatically by cliapp
. The FILE
is a manual page marked up
using the -man
macros for troff
(1). It should have empty
sections, and cliapp
will fill them
in. The output it to the standard output.
foo --generate-manpage=foo.1.in >
You would keep the source code for the manual page in foo.1.in
your Makefile produce foo.1
as shown above.
provides a way for the application to have subcommands
the style of git
(1), for example. If the application is called
, then it can have subcommands such as foo search
, and foo
. The application gets to define the name and meaning of each
subcommand. However, all settings (options and configuration files) are
global, and can be used with all subcommands. It is up to each subcommand what
settings it obeys.
If there are any subcommands, cliapp
automatically adds the help
subcommand. It allows you to get the help text for a specific subommand:
foo help print
, for example.
reads a list of configuration files at startup, on behalf of the
application. The name of the application is included in the name. In the
filenames below, the application name is progname
- Global configuration file.
- More global configuration files. These are read in ASCII
- Per-user configuration file.
- More per-user configuration files. Again, ASCII sorted
In addition, the XDG Base Directory specification is followed, if the Python
library is installed. In that case, environment variables
can be set to set additional location in which files are search for. The fixed
names above are always search; the XDG ones are search additionally.