# Command

The command object serves two purposes, it:

  1. Defines the root CLI application (command).
  2. 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 commands definition).

bashly.yml
name: rush
help: Personal package manager
version: 0.6.5

commands:
- name: add
  short: 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
  short: 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

# name

The name of the script or sub-command.

# short

An additional, optional pattern, usually used to denote a one letter variation of the command name.

You can add * as a suffix, to denote a starts with pattern - for example:

bashly.yml
name: download
short: d*  # anything that starts with d

# help

The header text to display when using --help.

This option can have multiple lines. In this case, the first line will be used as summary wherever appropriate.

# footer

Add a custom message that will be displayed at the end of the --help text.

Footer Example

# group

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, and needs to be specified only for the first command in each group.

Command Groups Example

# version

The string to display when using --version.

# default

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 required argument.

Default Command Example

# args

Specify the array of positional arguments this script needs.

Argument
/configuration/argument/

# flags

Specify the array of option flags this script needs.

Flag
/configuration/flag/

# commands

Specify the array of commands. Each command will have its own args and flags.

Commands Example Sub-Commands Example

# catch_all

Specify that this command should allow for additional arbitrary arguments or flags.

It can be set in one of three ways:

  • Set to true to just enable it.
  • Set to a string, to show this string in the usage help text.
  • Set to a hash containing label, help and required keys, to show a detailed help for it when running with --help. By default, catch_all arguments are optional, but you can specify required: true to 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).

Catch All Example Catch All Advanced Example

# completions

Specify an array of additional completion suggestions when used in conjunction with bashly add comp.

Bash Completion
/advanced/bash-completion/

# environment_variables

Specify an array of environment variables required or desired by your script.

Environment Variable
/configuration/environment-variable/

# dependencies

Specify an array of any required external dependencies (commands). The script execution will be halted with a friendly error unless all dependency commands exist.

Dependencies Example

# examples

Specify an array of examples to show when using --help. Each example can have multiple lines.

# extensible

Specify that this command can be extended by external means.

Extensible Scripts
/advanced/extensible-scripts/