---
name: "cli-generate"
section: "1"
platform: "linux"
package: "libbg-dev"
version: "2.04+dfsg-8+b9"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cli-generate"
---

# cli-generate(1)

Generate source and documentation from CLI descriptions

## NAME

cli-generate - Generate source and documentation from CLI descriptions

## SYNOPSIS

**cli-generate** \[ **-c** \| **-h** \| **-m** \| **-w** \] *FILENAME.cli*

## DESCRIPTION

### Operation

**cli-generate** reads in a CLI (command line interface) description file, parses it into its various sections, and prints out one of a set of output files.  In typical usage, that output would be directed to a file and later compiled or included in other sources.

The CLI file (named **PROGRAM***.cli*) is divided into two parts, a header (formatted much like a standard mail header) and a series of sections.  Headers and sections other than those specified below are ignored.  All headers and sections are optional.

### File Format

```
file = header "\n" *section
header = *(header-line "\n")
header-line = header-field ":" whitespace value
whitespace = *(SPACE / TAB)
section = "[" name "]" "\n" lines
lines = *( line "\n" )
```

### Headers

- **Description:**

  A one-line description of what the program does.

- **Include:**

  Add C statements to #include the given source file.  Must be formatted as either *\<file\>* or *file*

- **Min:**

  The minimum number of allowed non-option arguments.  Defaults to 0.

- **Max:**

  The maximum number of allowed non-option arguments.  Negative values mean unlimited.  Defaults to -1.

- **Show-Pid:**

  Set to non-zero if the resulting program is to show its PID with every output message.  Defaults to 0.

- **Usage:**

  A one-line description of the intended usage.  Defaults to empty.

### Section Names

- **\[prefix\]**

  The text in this section is shown in the command usage before the options description.

- **\[options\]**

  The list of options this program accepts.  See below for their format.

- **\[suffix\]**

  The text in this section is shown in the command usage after the options description.

- **\[description\]**

  - **\[return value\]**

  - **\[errors\]**

  - **\[examples\]**

  - **\[environment\]**

  - **\[files\]**

  - **\[see also\]**

  - **\[notes\]**

  - **\[caveats\]**

  - **\[diagnostics\]**

  - **\[bugs\]**

  - **\[restrictions\]**

  - **\[author\]**

  - **\[history\]**

  These sections are formatted and copied into the man page in the standard order.

### Options Format

```
options = *(option / separator)
option = option1 "\n" option2 "\n" *(line "\n")
option1 = [shortopt] [longopt] type ["=" flag-value] variable ["=" init]
option2 = helpstr ["=" default]
separator = "-- " text "\n"
shortopt = "-" character
longopt = "--" word
type = "FLAG" / "COUNTER" / "INTEGER" / "UINTEGER" / "STRING" / "STRINGLIST" / "FUNCTION"
```

If not specified, *flag-value* and *init* are *0*, and *default* is empty.

### Formatting

Except for **\[prefix\]**, **\[options\]**, and **\[suffix\]**, all of the sections support formatting instructions similar to that of TeXinfo (but greatly simplified).

- *@strong{text}*

  Use "strong" (bold) text.

- *@command{text}*

  Indicate the name of a command.

- *@option{text}*

  Indicate a command-line option.

- *@emph{text}*

  Use "emphatic" (italicized) text.

- *@var{text}*

  Indicate a metasyntactic variable.

- *@env{text}*

  Indicate an environment variable.

- *@file{text}*

  Indicate the name of a file.

- *@code{text}*

  Indicate text that is a literal example of a piece of a program.

- *@samp{text}*

  Indicate text that is a literal example of a sequence of characters.

- *@example*

  - *@end example*

  The text between these two tags is indented.

- *@verbatim*

  - *@end verbatim*

  Everything between these two tags is passed as-is (verbatim) to the output.

- *@table @format*

  - *@end table*

  Mark up a two-column table, or "definition list".

- *@item paragraph*

  Add an item to a table.  The  *@item* starts a paragraph that will be the actual list entry.  Any subsequent paragraphs will be typeset seperately.

## OPTIONS

- **-c**

  Output C source code.

- **-h**

  Output C header file.

- **-m**

  Output a UNIX man page.

- **-w**

  Output HTML (web) markup.

## EXAMPLES

Here is a sample CLI file, containing many of the described elements.

```
Min: 1
Max: 1
Usage: PATH
Description: Create a file.
Show-Pid: 0
Include: <stdio.h>
[prefix]
If the given PATH is a directory, it is suffixed with another name.
[description]
@program generates a new random file from a variety of sources including
@command{ls} and @command{ps} output.
If the given @option{PATH} is a directory, it is suffixed with another
name of my choosing.
[options]
-v --verbose FLAG=1 opt_verbose
-t --type STRING opt_type = "type1"
The type of the file to generate. = type1
Possible types for this include @option{type1} and @option{base64}.
```

## AUTHOR

Bruce Guenter \<bruce@untroubled.org\>