# Flag

Specify flags (required or optional) used by your script.

bashly.yml
flags:
  - long: --ssh
    short: -s
    help: Clone using SSH.

  - long: --user
    short: -u
    arg: name
    help: Repository user name.
    required: true

  - long: --profile
    arg: name
    help: Profile name
    allowed: [production, stage, dev]
    default: dev

  - long: --verbose
    short: -v
    help: Verbosity level (up to -vvv)
    repeatable: true

  - long: --cache
    help: Enable cache
    conflicts: [--no-cache]

  - long: --no-cache
    help: Disable cache
    conflicts: [--cache]

The flag's value will be available to you as ${args[--output]} in your bash function (regardless of whether the user provided it with the long or short form).

Note

Bashly supports these additional flag formats as input:

-abc same as -a -b -c
-a=arg same as -a arg
--flag=arg same as --flag arg

Note

Most properties are optional, unless specified otherwise.

# Basic Options

# long

String Required (unless short is provided)

The long form of the flag, including the -- prefix.

# short

String Required (unless long is provided)

The short form of the flag, including the - prefix.

Note

If you define short only (without defining long), then the value will be available to you in the $args associative array using the short name, for example: ${args[-f]}.

Special handling for -v and -h

The -v and -h flags will be used as the short options for --version and --help respectively only if you are not using them in any of your own flags.

# help

String

The text to display when using --help. Can have multiple lines.

# arg

String

If the flag requires an argument, specify its name here.

# Common Options

# default

String / Array of Strings

The value to use in case it is not provided by the user. Implies that this flag is optional, and only makes sense when the flag has an argument.

When using repeatable, you may provide an array here. It will be provided to your script as a space delimited string (similar to how it is provided when the user inputs values).

Default Values Example

# required

Boolean

Specify if this flag is required.

# Advanced Options

# allowed

Array of Strings

Limit the allowed arguments to a given whitelist. Can be used in conjunction with default or required.

Remember to set the arg name when using this option.

Whitelist Example

# conflicts

Array of Strings

Specify that this flag is mutually exclusive with one or more other flags. The values of this array should be the long versions of the flags:
conflicts: [--other, --another]

Note

This option should be specified on both sides of the exclusivity.

Conflicts Example

# completions

Array of Strings

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

Remember to set the arg name when using this option.

Bash Completion

../../advanced/bash-completion/

# needs

Array of Strings

Specify that this flag needs one or more other flags when executed. The values of this array should be the long versions of the flags:
needs: [--other, --another]

Note

This option should be specified on both sides of the requirement.

Needy Flags Example

# private

Boolean

Setting this to true on any flag, will hide it from the help text.

Tip

To allow users to see private flags, see Settings private_reveal_key

# repeatable

Boolean

Specify that this flag can be provided multiple times.

When the flag does not have an argument, the user can provide it multiple times in the form of -v -v -v or -vvv. In this case, the received value will be the number of times it was entered.

When the flag has an argument, the user can provide it in the form of -d value1 -d "value 2". In this case, the received value will be formatted as a quoted, space-delimited string which you will need to convert to array with something like eval "data=(${args[--data]})".

Repeatable Flag Example

# unique

Boolean

Specify that the values for this flag must be unique. Non-unique values will be ignored.

This option only applies to flags that have both repeatable: true and an arg specified.

# validate

String

Apply a custom validation function.

Custom Validations

../../advanced/validations/