NAME

       cliapp - config file and option conventions for Python command line framework

DESCRIPTION

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

       Configuration  file variables and command line options are handled by cliapp 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 configuration settings.

       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  parsed.
       (--dump-config  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 means the same
       thing, regardless of what subcommand is being used.

   Configuration files
       Configuration files use INI file syntax.  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 files.

   String list settings
       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 line, separated
       by commas.  This is a non-standard extension to the INI file syntax.  There is no way to escape commas.

       Example:

              [config]
              pattern = foo, bar, foobar

   Boolean (true/false or on/off or yes/no) settings
       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 of yes, on, true, or the number 1, the setting is turned on.  Any other  value
       means it is turned off.

              [config]
              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 called foo, the option
       --foo will turn the setting on, and --no-foo 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 configuration file.

   Logging and log files
       Programs  using  cliapp  automatically support several options for configuring the Python logging module.
       See the --help output for 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.

       The  --trace  option enables additional debug logging, which is usually only useful for programmers.  The
       option configures the tracing library 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.

   Python profiling support
       You can run the application under the Python profiler (cProfile) by setting an environment variable.  The
       name of the variable is FOO_PROFILE, 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.

   Manual page generation
       cliapp can generate parts of a manual page: the  SYNOPSIS  and  OPTIONS  sections.   It  fills  these  in
       automatically   based   on   the   subcommand   and   settings   that   a   program  supports.   Use  the
       --generate-manpage=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 SYNOPSIS and OPTIONS  sections,  and  cliapp
       will fill them in.  The output it to the standard output.

       For example:

              foo --generate-manpage=foo.1.in > foo.1

       You  would  keep  the source code for the manual page in foo.1.in and have your Makefile produce foo.1 as
       shown above.

   Subcommands
       cliapp provides a way for the application to have subcommands, in the style of git(1), for  example.   If
       the  application  is  called  foo,  then  it can have subcommands such as foo search, and foo print.  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.

FILES

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

       /etc/progname.conf
              Global configuration file.

       /etc/progname/*.conf
              More global configuration files.  These are read in ASCII sorted order.

       ~/.progname.conf
              Per-user configuration file.

       ~/.config/progname/*.conf
              More per-user configuration files.  Again, ASCII sorted order.

                                                                                                       CLIAPP(5)