Skip to content
Terminal user interface library
Branch: master
Clone or download
lugray Merge pull request #64 from cFire/master
Fixes #63 by ignoring left and right keypresses
Latest commit 8fa2293 Mar 31, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add dev-infra as codeowner Mar 29, 2019
bin Rename constants/paths Dec 15, 2017
lib/cli Fixes #63 by ignoring left and right keypresses Mar 31, 2019
.gitignore gitignore gemfile.lock Jan 3, 2018
.rubocop.yml Run rubocop on codebase Dec 13, 2017
.travis.yml Initial May 31, 2017
Gemfile Fix Gemfile, update README Dec 9, 2017
LICENSE.txt Initial May 31, 2017 Add input selection and filtering Jan 28, 2019
Rakefile Get tests running, fix hilarious f&r fails Dec 15, 2017
cli-ui.gemspec bundler, whatever Jan 15, 2019
dev.yml Better test command for internal dev.yml Dec 13, 2017


CLI UI is a small framework for generating nice command-line user interfaces


gem install cli-ui

or add the following to your Gemfile:

gem 'cli-ui'

In your code, simply add a require 'cli/ui'. Most options assume CLI::UI::StdoutRouter.enable has been called.


This may not be an exhaustive list. Please check our documentation for more information.

Nested framing

To handle content flow (see example below)

CLI::UI::StdoutRouter.enable'Frame 1') do'Frame 2') { puts "inside frame 2" }
  puts "inside frame 1"

Nested Framing

Interactive Prompts

Prompt user with options and ask them to choose. Can answer using arrow keys, vim bindings (j/k), or numbers (or y/n for yes/no questions).

For large numbers of options, using e, :, or G will toggle "line select" mode which allows numbers greater than 9 to be typed and f or / will allow the user to filter options using a free-form text input.

CLI::UI.ask('What language/framework do you use?', options: %w(rails go ruby python))

Can also assign callbacks to each option

CLI::UI::Prompt.ask('What language/framework do you use?') do |handler|
  handler.option('rails')  { |selection| selection }
  handler.option('go')     { |selection| selection }
  handler.option('ruby')   { |selection| selection }
  handler.option('python') { |selection| selection }
  • Note that the two examples provided above are identical in functionality

Interactive Prompt

Free form text prompts

CLI::UI.ask('Is CLI UI Awesome?', default: 'It is great!')

Free form text prompt

Spinner groups

Handle many multi-threaded processes while suppressing output unless there is an issue. Can update title to show state.

spin_group =
spin_group.add('Title')   { |spinner| sleep 3.0 }
spin_group.add('Title 2') { |spinner| sleep 3.0; spinner.update_title('New Title'); sleep 3.0 }

Spinner Group

Text Color formatting

e.g. {{red:Red}} {{green:Green}}

puts CLI::UI.fmt "{{red:Red}} {{green:Green}}"

Text Format

Symbol/Glyph Formatting

e.g. {{*}} => a yellow ⭑

puts CLI::UI.fmt "{{*}} {{x}} {{?}} {{v}}"

Symbol Formatting

Progress Bar

Show progress of a process or operation.

CLI::UI::Progress.progress do |bar|
  100.times do

Progress Bar

Example Usage

The following code makes use of nested-framing, multi-threaded spinners, formatted text, and more.

require 'cli/ui'

CLI::UI::StdoutRouter.enable'{{*}} {{bold:a}}', color: :green) do'{{i}} b', color: :magenta) do'{{?}} c', color: :cyan) do
      sg =
      sg.add('wow') do |spinner|
        spinner.update_title('second round!')
        sleep (1.0)
      sg.add('such spin') { sleep(1.6) }
      sg.add('many glyph') { sleep(2.0) }
  CLI::UI::Frame.divider('{{v}} lol')
  puts CLI::UI.fmt '{{info:words}} {{red:oh no!}} {{green:success!}}'
  sg =
  sg.add('more spins') { sleep(0.5) ; raise 'oh no' }


Example Output


  • Run tests using bundle exec rake test. All code should be tested.
  • No code, outside of development and tests needs, should use dependencies. This is a self contained library


Bug reports and pull requests are welcome on GitHub at


The code is available as open source under the terms of the MIT License.

You can’t perform that action at this time.