Specification

Comment Tags

@describe

Sets the description for the command.

^Syntax
@describe description

# @describe A demo CLI

@cmd

Defines a subcommand.

^Syntax
@cmd description^?

# @cmd Upload a file
upload() {
  echo Run upload
}

# @cmd Download a file
download() {
  echo Run download
}

USAGE: prog <COMMAND>

COMMANDS:
  upload    Upload a file
  download  Download a file

@alias

Sets aliases for the subcommand.

^Syntax
name (, name)^*

# @cmd Run tests
# @alias t,tst
test() {
  echo Run test
}

USAGE: prog <COMMAND>

COMMANDS:
  test  Run tests [aliases: t, tst]

@arg

Defines a positional argument.

^Syntax
@arg name modifier^? param-value^? bind-env^? notation^? description^?

# @arg va
# @arg vb!                        required
# @arg vc*                        multi-values
# @arg vd+                        multi-values + required
# @arg vna <PATH>                 value notation
# @arg vda=a                      default
# @arg vdb=`_default_fn`          default from fn
# @arg vca[a|b]                   choices
# @arg vcb[=a|b]                  choices + default
# @arg vcc*[a|b]                  multi-values + choice
# @arg vcd+[a|b]                  required + multi-values + choice
# @arg vfa[`_choice_fn`]          choice from fn
# @arg vfb[?`_choice_fn`]         choice from fn + no validation
# @arg vfc*[`_choice_fn`]         multi-values + choice from fn
# @arg vfd*,[`_choice_fn`]        multi-values + choice from fn + comma-separated list
# @arg vxa~                       capture all remaining args
# @arg vea $$                     bind-env
# @arg veb $VEB <PATH             bind-named-env

@option

Defines an option argument.

^Syntax
@option short^? long modifier^? param-value^? bind-env^? notations^? description^?

# @option    --oa                   
# @option -b --ob                   short
# @option -c                        short only
# @option    --oc!                  required
# @option    --od*                  multi-occurs
# @option    --oe+                  required + multi-occurs
# @option    --of*,                 multi-occurs + comma-separated list
# @option    --ona <PATH>           value notation
# @option    --onb <FILE> <FILE>    two-args value notations
# @option    --onc <CMD> <FILE+>    unlimited-args value notations
# @option    --oda=a                default
# @option    --odb=`_default_fn`    default from fn
# @option    --oca[a|b]             choice
# @option    --ocb[=a|b]            choice + default
# @option    --occ*[a|b]            multi-occurs + choice
# @option    --ocd+[a|b]            required + multi-occurs + choice
# @option    --ofa[`_choice_fn`]    choice from fn
# @option    --ofb[?`_choice_fn`]   choice from fn + no validation
# @option    --ofc*[`_choice_fn`]   multi-occurs + choice from fn
# @option    --ofd*,[`_choice_fn`]  multi-occurs + choice from fn + comma-separated list
# @option    --oxa~                 capture all remaining args
# @option    --oea $$               bind-env
# @option    --oeb $OEB <PATH>      bind-named-env

@flag

Defines a flag argument. Flag is a special option that does not accept any value.

^Syntax
@flag short^? long*^? bind-env^? description^?

# @flag     --fa 
# @flag  -b --fb         short
# @flag  -c              short only
# @flag     --fd*        multi-occurs
# @flag     --ea $$      bind-env
# @flag     --eb $EB     bind-named-env

@env

Defines an environment variable.

^Syntax
@arg NAME!^?param-value^? notation^? description^?

# @env EA                 optional
# @env EB!                required
# @env EC=true            default
# @env EDA[dev|prod]      choices
# @env EDB[=dev|prod]     choices + default

@meta

Adds metadata.

^Syntax
@meta name value^?

syntax	scope	description
@meta version <value>	any	Set the version for the command.
@meta binname <value>	root	Set binary name for usage, defaults to script file name.
@meta dotenv [<path>]	root	Load a dotenv file from a custom path, if present.
@meta default-subcommand	subcmd	Set the current subcommand as the default.
@meta require-tools <tool>...	any	Require certain tools to be available on the system.
@meta man-section <1-8>	root	Override the section for the man page, defaulting to 1.
@meta inherit-flag-options	root	Subcommands will inherit the flags/options from their parent.
@meta combine-shorts	root	Short flags/options can be combined, e.g. prog -xf => prog -x -f .
@meta external-subcommands	root	Enable external subcommands: scripts named <cmd>-<name>.sh in the same directory.
@meta symbol <param>	any	Define a symbolic parameter, e.g. +toolchain, @argument-file.

# @meta version 1.0.0
# @meta dotenv
# @meta dotenv .env.local
# @meta require-tools git yq
# @meta man-section 8
# @meta symbol +toolchain[`_choice_fn`]

Syntax parts

short

A single character abbreviation for a flag/option.

^Syntax
   -short-char
| +short-char

long

A descriptive name for a flag/option.

^Syntax
  -- long-name
| -long-name
| +long-name

modifier

Symbols used to modify param behavior:

^Syntax
  !
| * separated-char^?
| + separated-char^?

• !: The option is required and must be provided.
• *: multi-occurs for @option; multi-values for @arg;
• +: The option is required and can be used multiple times.

param-value

Ways to specify values for params:

^Syntax
  =value
| =`fn-name`
| [choices]
| [=choices]
| [`fn-name`]
| [?`fn-name`]

choices

Define a set of acceptable values for an param

^Syntax
value (| value)^*

notations

Placeholders in help messages and usage instructions:

^Syntax
(notation )^* notation-last

notation

^Syntax
< value >

• FILE/PATH: complete files
• DIR: complete directories

notation-last

^Syntax
< value notation-modifier^? >

notation-modifier

Symbols used within the last notation to specify value requirements

^Syntax
  *
| +
| ?

• *: Zero or more values are allowed.
• +: One or more values are allowed.
• ?: Zero or one value is allowed.

short-char

A-Z a-z 0-9 ! # $ % * + , . / : = ? @ [ ] ^ _ { } ~

separated-char

, : @ | /

bind-env

Link environment variables to params:

• $$: Automatically use the parameter's name in uppercase as the environment variable name, prefixed with the command name (e.g. --port $$ in command serve becomes SERVE_PORT).
• $NAME: Use a specific environment variable name.

description

Plain text for documentation and usage information

# @describe Can be multiline 
#
# Extra lines after the comment tag accepts description, which don't start with an `@`,
# are treated as the long description. A line which is not a comment ends the block.