Prompt makes it easy to build slick command-line applications with Tab Completion, Command History, and Built-in Help

gem install prompt

Commands are defined with a Sinatra-inspired DSL:

require 'prompt'
extend Prompt::DSL

command "look" do
  puts "You're in a dark room."
end

command "say :something" do |something|
  puts "You say '#{something}'"
end

param :direction, %w(north east south west)

command "go :direction" do |direction|
  puts "You walked #{direction} and were eaten by a grue."
end

Prompt::Console.start

Tab completion is hooked up automatically after you define your commands and parameters

$ my_app
> g<TAB>
> go <TAB>
east   north  south  west
> go n<TAB>
> go north

Command history is enabled automatically. You can scroll through the history with the UP and DOWN keys. You can search the history with CTRL-R.

You can preserve the history between runs by specifying a history filename when starting the console

history_file = File.join(ENV["HOME"], ".my-history")
Prompt::Console.start history_file

The help command is built-in. It will print all of the commands that you've defined in your app.

$ my_app
> help
Console commands

  help               List all commands
  help -v            List all commands, including parameters
  exit               Exit the console

Move

  go <direction>     Walk in the specified direction

Interact

  look               Look around
  say <something>    Say something

You can provide a description for a command before defining it. Descriptions are displayed next to each comand in the built-in help.

desc "Look around"
command "look" do
  ...
end

You can put commands in logical groups. This only affects how help is printed.

group "File commands"

command ...
command ...

group "Directory commands"

command ...

Parameters can be used in a command:

command "name :first :last" do |first, last|
  puts "Hi #{first} #{last}"
end

Here, the parameters are named first and last. Their values are be passed as arguments to the command's block, in the order in which they appear.

Each :parameter only matches a single word. If you want to match multiple words to one parameter, use a *parameter.

command "cp *file :dest" do |files, dest|
  puts "You copied #{files.length} files to #{dest}"
end

It's not necessary to define a parameter before using it in a command, but doing so will allow you to provide a useful description and list of possible completions for the parameter.

param :name, "Description"

You can specify the completions for a parameter as a static list:

param :color, "A color", %w(red green blue)

or you can dynamically generate the completions using a block:

param :file, "JPG file" do
  Dir.glob "*.jpg"
end

A dynamic parameter's block may optionally take the partially-typed word as a parameter, to further limit the completions.

param :username do |starting_with|
  # Query database for usernames that start with the partially-typed word
  User.where("username LIKE '?%'", starting_with).pluck(:username)
end

The default prompt "> " can be changed before starting the console, or while it's running.

Prompt.application.prompt = "#{Dir.pwd}> "