Shell Completion

Generating Completion Scripts

Every command can automatically generate its shell completion script.

The supported shell environments are:

• bash
• zsh

To generate a script, use the generate_xxx_completion method of a command class.

class TicketToRide < Cli::Command
  class Options
    string "--by", any_of: %w(train plane taxi)
    arg "for", any_of: %w(kyoto kanazawa kamakura)
  end
end

puts TicketToRide.generate_bash_completion
# or
puts TicketToRide.generate_zsh_completion

See the gist for bash and the gist for zsh.

Zsh: Function vs Sourced Script

By default, generate_zsh_completion returns a script used as a zsh function. To generate a script that can be sourced, set the functional option to false.

TicketToRide.generate_zsh_completion(functional: false)

Setting Completion Methods

You can set a special completion method to each command line option/argument.

The method types are:

• word-list
• action
• command

Word-List

It replies specified word strings as completions.

class Horoscope < Cli::Command
  string "--star", completion: %w(
    aries
    taurus
    gemini
    cancer
    leo
    virgo
    libra
    scorpio
    sagittarius
    capricorn
    aquarius
    pisces
  )
end

An example output:

$ horoscope --star
aries        gemini       leo          libra        sagittarius  aquarius
taurus       cancer       virgo        scorpio      capricorn    pisces
$ horoscope --star a
aries  aquarius

[WIP]

Emulating the Bash's Actions (Experimental)

Crystal CLI supports the bash's native completion actions, the -A option of the compgen command. For zsh, Crystal CLI emulates the behavior by the zsh dependent code.