command object serves two purposes, it:
- Defines the root CLI application (command).
- Defines any nested sub-commands, if any.
Unless otherwise specified, these definitions can be used for both the root
command and sub-commands (under the
Most properties are optional, unless specified otherwise.
name: rush help: Personal package manager version: 0.6.5 commands: - name: add alias: a help: Register a local repository args: - name: repo required: true help: Repository name. - name: path required: true help: Path to the repository. examples: - rush add default ~/rush-repos/default - name: remove alias: r help: Unregister a local repository args: - name: repo required: true help: Repository name. flags: - long: --purge short: -p help: Also remove the local directory. examples: - rush remove bobby - rush remove bobby --purge
The name of the script or sub-command.
This command used to be called
short in bashly < 0.8.0
One or more additional optional names for this command. This can be used to create a shortcut for a command, or provide alternative names for it.
This option accepts either a string, or an array of strings.
You can add
* as a suffix, to denote a starts with pattern - for example:
name: index alias: i # simple shortcut name: download alias: d* # anything that starts with d name: upload alias: [u, push] # upload, u and push will all run the same command
The header text to display when using
This option can have multiple lines. In this case, the first line will be used as summary wherever appropriate.
Specify the array of positional arguments this script needs.
Specify the array of option flags this script needs.
Flags that are defined in a command that has sub-commands, are considered "global flags", and will be available to all sub-commands, in addition to any flag defined in any of the sub-commands themselves.
The docker-like example demonstrates this feature.
Specify the array of commands. Each command will have its own args and flags.
commands on a given command implies that this command does not have flags or args.
The string to display when using
Setting this to
true on any command, will cause any unrecognized command
line to be passed to this command. This means that it should be used only for
command that have at least one argument.
Specify an array of environment variables required or desired by your script.
Specify an array of examples to show when using
--help, or a multi-line
Add a custom message that will be displayed at the end of the
In case you have many commands, use this option to specify a caption to display before this command.
This option is purely for display purposes.
Specify that this command should allow for additional arbitrary arguments or flags.
It can be set in one of three ways:
- Set to
trueto just enable it.
- Set to a string, to show this string in the usage help text.
- Set to a hash containing
requiredkeys, to show a detailed help for it when running with
--help. By default,
catch_allarguments are optional, but you can specify
required: trueto require at least one argument.
To access arguments captured by
catch_all in your script, use the
$other_args array (or call the
inspect_args command to see them).
Specify an array of additional completion suggestions when used in conjunction
bashly add comp.
Specify an array of any required external dependencies (commands). The script execution will be halted with a friendly error unless all dependency commands exist.
Setting this to
always on any command that has sub-commands, will
show its sub-commands in the help or usage text of the parent command.
- Set to
trueto show the sub-commands only when the parent command is executed with
- Set to
alwaysto show the sub-commands also when the parent command is executed without any arguments.
You can use
expose with the
Specify that this command can be extended by external means.
The path (relative to
src) to the partial source code file, in case you wish
to store your source files in a different path than the default one.
This is useful for scripts that contain many commands.
Add custom filter functions that will prevent the command from running unless certain conditions are met.
The base name of the internal functions bashly will use when generating the script.
This is useful for scripts that contain several commands that otherwise evaluate to the same internal function name.
Note that the name specified here is just used as a base name. Bashly will generate several functions from it:
<cli name>_<base function name>_command
<cli name>_<base function name>_usage
- and possibly more
Under most circumstances you should avoid using this directive. It is provided as a "last resort" mechanism to help in solving more complex scenarios.
Setting this to
true on any command, will hide it from the command list.