Bash Completion

Bashly comes with a built-in bash completions generator, provided by the completely gem.

By running bashly add completions, you can add this functionality to your script in one of three ways:

Creates a function in your ./src/lib directory that echoes a completion script. You can then call this function from any command (for example yourcli completions) and your users will be able to install the completions by running eval "$(yourcli completions)".

Creates a standalone completions script that can be sourced or copied to the system's bash completions directory.

Creates the raw data YAML file. This is intended mainly for development purposes.

The bash completions generation is completely automatic, but you will have to regenerate the completion function whenever you make changes to your bashly.yml file.

Tip

By running bashly generate --upgrade, your completions function (generated with bashly add completions) will be regenerated.

Custom argument completions

In addition to the automatic suggestion of subcommands and flags, you can instruct bashly to also suggest files, directories, users, git branches and more.

For positional arguments, add completions to the argument that should receive these suggestions:

bashly.yml
commands:
- name: upload
  help: Upload a file
  args:
  - name: source
    help: File to upload
    required: true
    completions:
    - <file>
    - <directory>
    - $(git branch 2> /dev/null)

The completions option is still supported on commands as a fallback for positional arguments, but it is discouraged for new configurations. Prefer placing completions directly on the relevant args entry.

Custom flag completions

For flag values, add completions to flags that have an arg. Similarly to the allowed option for arguments and flags, the allowed list is added to the suggestions automatically (without the need to use completions).

bashly.yml
commands:
- name: login
  help: Login to SETI
  flags:
  - long: --user
    arg: username
    completions:
    - <user>
  - long: --protocol
    arg: protocol
    allowed:
      - ssh
      - telnet

Anything between <...> will be added using the compgen -A action flag.
Anything else will be appended to the compgen -W flag.

Note

In case you are using the Argument allowed option or the Flag argument allowed option, these will be automatically added to the completions list as well.

Completions in ZSH

If you are using Oh-My-Zsh, bash completions should already be enabled, otherwise, you should enable completion by adding this to your ~/.zshrc (if it is not already there):

# Load completion functions
autoload -Uz +X compinit && compinit
autoload -Uz +X bashcompinit && bashcompinit

After adding this (and restarting your session), you should be able to source any bash completion script in zsh.

Additional documentation

For more information about these custom completions, see the documentation for the completely gem.

Example

Bash Completions Example