# Bash Completion

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

By running bashly add completions commands, 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 command completions

In addition to the automatic suggestion of sub-commands and flags, you can instruct bashly to also suggest files, directories, users, git branches and more. To do this, add another option in your bashly.yml on the command you wish to alter:

bashly.yml
commands:
- name: upload
  help: Upload a file
  completions:
  - <directory>
  - <user>
  - $(git branch 2> /dev/null)

# Custom flag completions

The completions option is also available on flags that have an arg. Similarly to the allowed option for arguments, 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 is it 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