Skip to content
MarkdownTables
Developer Template5 columns · 6 sample rows· Updated

CLI Options & Arguments Reference Markdown Table Template

An options table is what people open with a half-typed command sitting in their terminal. For every flag it settles four things: the long name, the one-letter shortcut if there is one, whether the flag swallows the next word as its value, and what the tool does when the flag is absent. --help covers the same ground, but a table in the README is searchable, linkable from issues, and has room for what a one-line help string cannot hold: environment overrides, flags that cancel each other out, and behaviour that matters in CI.

Edit This Template

Edit cells, add rows, or sort — the Markdown updates live
Row
1
--output <dir>
-o
./dist
2
--format <type>
-f
Output format (markdown, csv, json)
markdown
3
--dry-run
-n
false
4
--verbose
-v
false
5
--concurrency <n>
-c
4
6
--version
-V
Output
| Option Flag         | Alias |  Type   | Description                                    |    Default |
| :------------------ | :---: | :-----: | :--------------------------------------------- | ---------: |
| `--output <dir>`    | `-o`  |  path   | Destination directory for generated files      |   `./dist` |
| `--format <type>`   | `-f`  |  enum   | Output format (`markdown`, `csv`, `json`)      | `markdown` |
| `--dry-run`         | `-n`  | boolean | Simulate changes without writing files to disk |    `false` |
| `--verbose`         | `-v`  | boolean | Enable debug log output to stderr              |    `false` |
| `--concurrency <n>` | `-c`  | integer | Maximum parallel worker threads                |        `4` |
| `--version`         | `-V`  | boolean | Display binary version and exit                |          — |
6 rows × 5 columns
Rendered Preview
Option FlagAliasTypeDescriptionDefault
--output <dir>-opathDestination directory for generated files./dist
--format <type>-fenumOutput format (markdown, csv, json)markdown
--dry-run-nbooleanSimulate changes without writing files to diskfalse
--verbose-vbooleanEnable debug log output to stderrfalse
--concurrency <n>-cintegerMaximum parallel worker threads4
--version-VbooleanDisplay binary version and exit—

When to Use This Table

Different readers want different columns. Someone writing a CI script copies the long form, because --concurrency 8 still makes sense to the next person reading the pipeline file, while -c 8 does not. Someone at an interactive prompt scans the Alias column for the shortest spelling. The maintainer adding a new option checks the table before claiming a letter, so -c does not end up meaning “concurrency” in one subcommand and “config” in another.

A good options table is copied from, or tested against, the actual parser definition — clap, cobra, argparse, click, commander — so it cannot drift from --help. It shows which options take a value and which are plain switches, says how to turn a default-on switch off, and states precedence when the same setting can also come from an environment variable or config file. A weak one lists flags with a three-word description, puts quotes around defaults, and quietly lets -v mean both verbose and version.

What Goes in Each Column

ColumnAlignmentWhat to put here
Option Flagleft :---The GNU-style long option with its value placeholder, in backticks: --output <dir>. Angle brackets mark a required value, square brackets an optional one (--color[=<when>]), and a trailing ... means the option may be repeated. Left-aligned so the double hyphens form a straight edge readers can scan.
Aliascenter :---:The single-hyphen, single-character short form, such as -o, or — when there is none. Short letters are scarce, so reserve them for options people type by hand every day. Follow established meanings where they exist: -h for help, -q for quiet, -n for dry run, -f usually for force.
Typecenter :---:How the parser treats the value. boolean means a switch that takes no argument at all; integer, path, string, and enum consume one argument; write list for repeatable or comma-separated options. Say in Description whether a relative path resolves against the working directory or the config file.
Descriptionleft :---Start with a verb (“Write”, “Skip”, “Limit”) and then add the constraints: enum members, valid range, interactions (“ignored when --dry-run is set”), and the environment variable that also sets it. If the option changes what is printed, say whether it goes to stdout or stderr.
Defaultright ---:The value used when the flag is omitted, unquoted and in backticks: ./dist, not "./dist". Right-aligned so numbers line up. When the default is computed, write the rule (“number of CPU cores”). Use — for action flags like --help and --version, which print and exit instead of setting anything.

How to Fill It In

  1. 1Capture the real interface first: run mytool --help and mytool <subcommand> --help, then open the parser definition in source. Help text is often edited by hand while the parser is the thing that actually runs.
  2. 2For each option, read the default from the parser, then check whether an environment variable or config file can supply the value. Write down the order the tool resolves them in, typically flag, then environment, then config file, then built-in default.
  3. 3Try the syntax forms a user might type and note which ones work: --output=dist and --output dist, -o dist and -odist, grouped switches like -nv, a repeated -vvv, and -- to end option parsing.
  4. 4Order the rows the way people look things up: global options first, then subcommand options alphabetically by long name, with --help and --version last.
  5. 5Escape every literal pipe. A placeholder like --format <markdown|csv|json> splits the row even inside backticks, so write \| instead (see escaping pipes in tables).
  6. 6Add a snapshot test that stores the --help output. When a pull request changes the snapshot, the reviewer knows the table needs the same change.

Ready-to-Paste Variations

Compact README version

Short and long forms share one cell, the way most --help screens print them. Good for a quick-start section where five columns would crowd the page.

| Option | Description |
| :--- | :--- |
| `-o, --output <dir>` | Write generated files to `<dir>` (default `./dist`) |
| `-f, --format <markdown\|csv\|json>` | Output format (default `markdown`) |
| `-n, --dry-run` | Show what would change without writing anything |
| `-q, --quiet` | Print errors only |
| `-h, --help` | Show help and exit |

With environment variable and config file sources

For tools that read the same setting from several places. The columns appear in precedence order, so the leftmost source wins.

| Flag | Environment variable | Config key | Default |
| :--- | :--- | :--- | ---: |
| `--concurrency <n>` | `MYTOOL_CONCURRENCY` | `build.concurrency` | CPU cores |
| `--output <dir>` | `MYTOOL_OUTPUT` | `build.outDir` | `./dist` |
| `--no-color` | `NO_COLOR` (any non-empty value) | `ui.color = false` | colour on a TTY |
| `--log-level <level>` | `MYTOOL_LOG_LEVEL` | `log.level` | `info` |

Subcommand overview

For git-style tools, document the subcommands first and link each one to its own options table.

| Command | Arguments | What it does |
| :--- | :--- | :--- |
| `mytool init` | `[dir]` | Create a config file in `dir` (current directory if omitted) |
| `mytool build` | `<entry>...` | Build one or more entry files |
| `mytool watch` | `<entry>` | Rebuild on every file change until interrupted |
| `mytool clean` | — | Delete the output directory |

Common Mistakes

  • Describing --verbose as sending debug output to stdout.

    Diagnostics belong on stderr so that mytool --verbose > out.json still produces clean data. Fix the code if necessary, then write “to stderr” in the description.

  • Picking surprising short letters, such as -d for dry run.

    Many users expect -n there, because make -n, rsync -n, and git clean -n all use it. When a familiar letter is already taken, leave the option without an alias rather than inventing a meaning nobody will guess.

  • Showing a value for a switch, like --dry-run <bool> or --verbose=true.

    Most parsers reject an argument on a boolean flag. Document the bare switch, and if it defaults to on, document the negated form (--no-color) as its own row.

  • Writing an optional-value long option with a space: --color always.

    With GNU getopt_long, an optional argument must be attached with = (--color=always). Separated by a space, always is read as a positional operand. Show the = form in the table.

  • Wrapping defaults in quotes, as in "markdown".

    The shell strips quotes, so they are not part of the value, and readers copy them into config files where they are. Write the bare value in backticks.

Related Markdown Table Templates

Browse all 50 templates
Developer

Docker Container Ports & Volumes Matrix

Map container service names, host ports, guest ports, protocols, volume bindings, and persistence scopes.

Open template
Developer

HTTP Status Codes & API Error Mapping

Standardized API error responses, error payload codes, HTTP status mapping, retryability, and troubleshooting steps.

Open template
Developer

Relational Database Table DDL Schema

Document database tables, column names, SQL types, nullability, keys (PK/FK), default values, and column semantics.

Open template
FAQ

CLI Options & Arguments Reference: Frequently Asked Questions

Why do some flags use one hyphen and others two?

POSIX utility conventions define single-character options after one hyphen, which can be grouped (-nv). GNU added long, readable options after two hyphens. Some ecosystems differ: Go’s standard flag package accepts one or two hyphens for any flag name, and find uses single-hyphen words like -name.

What does a bare -- do on the command line?

It ends option parsing. Everything after it is treated as an operand even if it starts with a hyphen, so rm -- -draft.md deletes a file literally named -draft.md. If your tool passes arguments through to another program, document that behaviour.

Should --help and --version be in the table?

Yes, as the last two rows. The GNU Coding Standards expect every program to support both and to print to stdout and exit successfully. Listing them also shows which short letters they occupy, which settles the -v versus -V question for readers.

How do I document a flag that can be repeated?

Add ... to the placeholder (--include <glob>...) and state in Description whether repeated values accumulate or the last one wins. For counting switches such as -vvv, say what each level adds, for example warnings, then info, then debug.