Natively Pronounced Mandarin


    1.0.34 • Public • Published

    Command Line Interface

    Build Status npm version Coverage Status

    Define command line interfaces as markdown

    Describe a command line interface as an easy to read man-style markdown document and compile it to a program descriptor; the JSON program descriptor can then be used by the program implementation to parse and validate arguments.

    The markdown program definitions can be converted to man pages, help files and shell completion scripts.

    Encourages a document first approach to writing command line interfaces in a fluid natural language writing style.


    npm i mkcli --save

    For the command line interface install mkdoc globally (npm i -g mkdoc).


    To compile all output types to the same directory as the input file:


    Compile all output types to a specific directory:

    mkcli -o build

    Compile a specific output type:

    mkcli -t man

    Compile a specific output type to a particular directory:

    mkcli -t zsh --zsh build/zsh

    If you have a lot of programs pass a directory and all markdown documents in the directory are compiled:

    mkcli doc/cli -o build

    You may pipe input for more control over the output; to set a man page title:

    mkcat | mkcli -t man | mkman --title program > program.1

    See help for more options.

    Example files for a simple working program are in doc/example:

    Every program in the mkdoc toolkit is compiled using this library:


    Defining Programs

    The markdown document defines sections that start with a level one heading and continue until the next level one heading or the end of file is reached.

    The sections that have special meaning to the compiler are NAME, SYNOPSIS, DESCRIPTION, COMMANDS and OPTIONS.

    It is considered best practice to declare these sections in the order listed.

    All other sections are deemed to be man page sections they are ignored from help output by default (but may be included at compile time) and are always included when generating man pages.

    Section headings are not case-sensitive so you can use upper case, title case or lower case but they must match exactly.


    Like man pages the name section is required and it must include a brief summary of the program after the program name. Delimit the program name from the short summary using a hyphen surrounded by spaces as shown below.

    The name section must be the first section in the file otherwise the compiler will error.

    The program name and summary is extracted from the first paragraph under the NAME heading:

    prg - short program summary

    For subcommands define parent names for a command using whitespace between the words:

    prg list - perform list action

    Add a list when a program can have multiple names:

    prg - short program summary
    + prg-alias


    The program synopsis is created from all code block elements under the SYNOPSIS heading:

    prg - short program summary
        [options] [file...]

    It is a compiler error if any other type is declared in the synopsis section.


    The program description is created from all block level elements under the DESCRIPTION heading:

    prg - short program summary
    An extended description that can include paragraphs, lists, code blocks and other block level elements.

    Note that the help output only includes paragraphs so some meaning may be lost if you include lists, code blocks or block quotes. For this reason it is recommended that the description section only contain paragraphs.

    If you mix content in the description section you can use the -d, --desc option when generating the help file to restrict the number of paragraphs included in the help output.

    Consider this example:

    prg - short program summary
    Simple program.
    Run with:
        cat | prg

    Context would be lost on the second paragraph because the code block would not be included in the help output, whilst it would make perfect sense in the man output.

    To prevent this loss of context just include the first paragraph in the help output:

    mkcat | mkcli --desc 1 | mktext


    Program arguments are declared with a heading of OPTIONS and a list following the heading.

    Note the list bullet character + is preferred because it creates a more idiomatic listing in generated man pages.

    prg - short program summary
    + `-i, --input [FILE...]` Input files
    + `-o, --output [FILE]` Output file

    An argument is declared as a list item whose first child is an inline code element which defines a specification.

    The specification is parsed into an object representing the argument which may be of type flag, option or command.

    The remaining list item content after the specification is treated as a description for the argument.


    An argument specification with no value is treated as a flag option:

    + `-v, --verbose` Print more information

    To create an option argument specify a value in either [] or <>:

    + `-o, --output [FILE]` Output file

    When the <> notation is used it indicates that that the option is required:

    + `-t, --type <TYPE>` Output format

    The parsed option will have the required flag set.


    To signify that an option argument is repeatable include an ellipsis:

    + `-i, --input [FILE...]` Input files

    The parsed option will have the multiple flag set.

    Type Info

    You can associate some type information with the {} notation:

    + `-i, --indent [NUM] {Number}` Amount of indentation

    The parsed option will have the kind property set to Number.

    You can delimit multiple types with | and kind is expanded to an array. This is useful to indicate an argument may be of multiple types or if you want to treat an argument value as an enum:

    + `-t, --type [VAL] {json|help|man}` Renderer type
    Default Value

    To specify a default value for the option use the = operator in the type:

    + `-i, --indent [NUM] {Number=2}` Amount of indentation

    The parsed option will have the kind property set to Number and the value property set to 2.

    You can just specify the default value using:

    + `-i, --indent [NUM] {=2}` Amount of indentation

    In which case the kind property will be undefined and the value property is set to 2.


    Commands are declared in the same way as program arguments but under the COMMANDS heading:

    prg - short program summary
    + `ls, list` List tasks
    + `i, info` Print task information

    They allow you to create complex programs with options specific to a command.

    Command files are loaded and compiled automatically following a naming convention. Using the above example to define the list command create a file named

    list - list tasks
    + `-a, --all` List all tasks
    + `-t=[TYPE...]` List tasks of TYPE

    Will result in the compiled tree containing options specific to the list command.


    When a program is created from a source markdown document each argument and command is given a key for the resulting map. This key is generated automcatically by using the longest argument (or command) name and converting it to camel case.

    If you wish to use a fixed key you can add an identifier followed by a colon (:) to the beginning of the specification:

    prg - short program summary
    + `tasks: ls, list` List tasks
    + `verbose: -v` Print more information

    Manual Sections

    A heading that is not matched by any of the rules above is treated as a manual section:

    prg - short program summary
    The environment variable FOO changes the behaviour to `bar`.

    The section ends when the next level one heading is encountered or the end of the file is reached.

    Synopsis Expansion

    Unless disabled the synopsis declaration is expanded for the man and help output types.


    Use the notation [flags] (or <flags>) in the synopsis and it will be replaced with all short form (single character) flag options (for example: -xvf).


    Use the notation [options] (or <options>) in the synopsis and it will be replaced with all option names that are not declared in the synopsis and were not expanded using the [flags] notation.

    Exclusive Options

    You should indicate mutually exclusive options using a vertical bar between option names.

    When compiling to JSON the synopsis is parsed and any mutually exclusive declarations are added to the output using the target option keys.

    It is a compiler error if the target option is not declared.

    Expansion Example

    Given a definition such as:

    prg - short program summary
        [flags] [options] [--xml|--html] <file...>
    + `-X, --xml` Print as XML
    + `-H, --html` Print as HTML
    + `-V` Print more information
    + `-h, --help` Display help and exit
    + `--version` Print the version and exit

    The synopsis is expanded to:

    prg [-XHVh] [--help] [--version] [--xml|--html] <file...>

    Compiling Programs

    To compile the markdown document to a JSON program descriptor run:

    mkcli -t json

    Now you have a JSON document that describes your program commands and options.

    Creating Documentation

    Once you have defined the program you will want to generate a man page and some help text.

    To create the help text run:

    mkcli -t help

    For a man page run:

    mkcli -t man

    Help Styles

    The default column help style (col) should suit most purposes however the other styles can be useful. The list style renders a list of the commands and options which is designed for when you have very long argument names or a few arguments that require long descriptions.

    The cmd style is a list of command names (options are not printed) designed to be used when a program has lots of commands and a command is required. Typically the program would show this help page when no command was specified to indicate to the user a command is required.

    Sometimes you may want very minimal help output that just includes the usage synopsis in which case use the usage style.

    Help Sections

    Sometimes when creating help files you may want to include a section from the manual, possibly you want to include an Environment section to show the environment variables your program recognises.

    Pass regular expression patterns using the --section option and if they match a section heading the section will be included in the help after the commands and options.

    To include an Environment section you could use:

    mkcli -t help -S env

    To include the Environment and Bugs sections you could use:

    mkcli -t help -S env -S bug

    Or if you prefer:

    mkcli -t help -S '(env|bug)'

    See the help for more options available when creating help and man pages.


    Completion scripts are currently available for zsh. To install a completion script for a program copy the script to a directory in $fpath or modify ~/.zshrc to autoload the directory containing the completion script:

    fpath=(/path/to/completion $fpath)

    A full working completion example is the notes test fixture.

    Sometimes you may wish to reload a completion for testing purposes:

    unfunction _notes && autoload -U _notes


    Some option value specifications map to zsh completion functions:

    • user: :user:_users
    • group: :group:_groups
    • host: :host:_hosts
    • domain: :domain:_domains
    • file: :file:_files
    • dir: :directory:_directories
    • url: :url:_urls

    Such that an option specification such as:

    + `-i, --input [file...]` Input files
    + `-o, --output <dir>` Output directory

    Will result in the _files completion function being called to complete file paths for the --input option and the _directories function for the --output option. Note that the ellipsis (...) multiple flag is respected so --input will be completed multiple times whilst --output will only complete once.

    For options that specify a list of types the _values completion function is called.

    + `-t, --type=[TYPE] {json|yaml}` Output type

    Results in automatic completion for the --type option to one of json or yaml.

    Actions are enclosed in double quotes (") so you may use single quotes and paired double quotes but not a single double quote which will generate an unmatched " zsh error.

    Synopsis Completion

    The program synopsis section is inspected and will use completion functions when a match is available, so a synopsis such as:

    [options] [files...]

    Will result in the _files completion function called, see above for the list of matches and completion functions.

    Sometimes you may need to create a custom completion list; you can set the info string of fenced code blocks in the synopsis section to inject scripts. The value may be either zsh-locals to inject code into the beginning of the body of the generated completion function and zsh to add to the list of completion actions.

    A real-world example is mk (program definition and compiled completion script) which completes on the available task names.

    Specification Completion

    You may wish to change the zsh action taken per option, this can be done by appending a colon and the zsh action to an option specification:

    + `-p, --package=[FILE] :file:_files -g '+.json'` Package descriptor

    Which will complete files with a .json extension for the --package option.

    Command Completion

    Commands are recursively added to the completion script; they are completed using the following rules:

    • Required commands (<command> in the synopsis) will not list options by default.
    • Command options inherit from the global options.
    • Command options cascade to child options.
    • Rest pattern matches (*: :file:_files for example) are respected.

    It is recommended you use a program synopsis with the command first:

        <command> [options] [files...] 

    Or if the command is not required:

        [command] [options] [files...] 

    Which is because command completion is terminated when an option is intermingled with the command hierarchy. Consider a program that has the command structure notes > list > bug|todo|feature if you present a command line such as:

    notes list --private

    Completion will no longer be attempted on the list sub-commands. To put it another way commands must be consecutive for command completion to occur.


    Usage: mkcli [-frRCHFNPh] [--full] [--recursive] [--raw-synopsis] [--colon]
                 [--header] [--footer] [--newline] [--preserve] [--help]
                 [--version] [--package=<file>] [--type=<type>] [--style=<val>]
                 [--cols=<num>] [--split=<num>] [--desc=<num>] [--indent=<num>]
                 [--align=<type>] [--usage=<val>] [--section=<ptn...>]
                 [--json=<dir>] [--text=<dir>] [--man=<dir>] [--zsh=<dir>]
                 [--output=<dir>] [files...]
      Compiles markdown cli definitions.
      -p, --package=[FILE]    Use package descriptor
      -t, --type=[TYPE]       Output renderer type (json|help|man)
      -y, --style=[VAL]       Help output style (col|list|cmd|usage)
      -c, --cols=[NUM]        Wrap help output at NUM (default: 80)
      -s, --split=[NUM]       Split help columns at NUM (default: 26)
      -d, --desc=[NUM]        Number of description paragraphs for help output
      -i, --indent=[NUM]      Number of spaces for help indentation (default: 2)
      -a, --align=[TYPE]      Alignment of first help column (left|right)
      -u, --usage=[VAL]       Set usage message for help synopsis (default: Usage:)
      -f, --full              Do not compact compiled descriptor
      -r, --recursive         Recursively load command definitions
      -R, --raw-synopsis      Do not expand synopsis
      -C, --colon             Append a colon to headings in help output
      -S, --section=[PTN...]  Include sections matching patterns in help output
      -H, --header            Include default header in help output
      -F, --footer            Include default footer in help output
      -N, --newline           Print leading newline when no header
      -P, --preserve          Do not upper case headings in man output
      -J, --json=[DIR]        Set output directory for json files
      -T, --text=[DIR]        Set output directory for help text files
      -M, --man=[DIR]         Set output directory for man pages
      -Z, --zsh=[DIR]         Set output directory for zsh completion
      -o, --output=[DIR]      Set output directory for all types
      -h, --help              Display help and exit
      --version               Print the version and exit




    Gets a source parser stream that transforms the incoming tree nodes into parser state information.

    Returns a parser stream.

    • opts Object parser options.



    Gets a compiler stream that transforms the parser state information to a program definition.

    Returns a compiler stream.

    • opts Object compiler options.



    Gets a destination renderer stream.

    When no type is specified the JSON renderer is assumed.

    Returns a renderer stream of the specified type.

    • opts Object renderer options.


    • type String=json the renderer type.


    load(def[, opts])

    Load a program definition into a new program assigning the definition properties to the program.

    Properties are passed by reference so if you modify the definition the program is also modified.

    Returns a new program.

    • def Object the program definition.
    • opts Object program options.


    run(src, argv[, runtime], cb)

    Load a program definition into a new program assigning the definition properties to the program.

    Properties are passed by reference so if you modify the definition the program is also modified.

    The callback function signature is function(err, req) where req is a request object that contains state information for program execution.

    Plugins may decorate the request object with pertinent information that does not affect the target object that receives the parsed arguments.

    Returns a new program.

    • src Object the source program or definition.
    • argv Array the program arguments.
    • runtime Object runtime configuration.
    • cb Function callback function.



    Created by mkdoc on August 3, 2016


    npm i mkcli

    DownloadsWeekly Downloads






    Last publish


    • muji
    • tmpfs