by Shopify

Shopify / cli-ui

Terminal user interface library

514 Stars 24 Forks Last release: almost 2 years ago (v1.2.1) MIT License 380 Commits 14 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


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
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 (

), or numbers (or y/n for yes/no questions).

For large numbers of options, using

, or
will toggle "line select" mode which allows numbers greater than 9 to be typed and
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


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

Text Format

Symbol/Glyph Formatting


=> a yellow ⭑
puts CLI::UI.fmt "{{*}} {{v}} {{?}} {{x}}"

Symbol Formatting

Status Widget

CLI::UI::Spinner.spin("building packages: {{@widget/status:1:2:3:4}}") do |spinner|
  # spinner.update_title(...)

Status Widget

Progress Bar

Show progress of a process or operation.

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

Progress Bar

Frame Styles

Modify the appearance of CLI::UI both globally and on an individual frame level.

To set the default style:

CLI::UI.frame_style = :box

To style an individual frame:

CLI::UI.frame('New Style!', frame_style: :bracket) { puts 'It's pretty cool!' }

The default style -

- is what has been used up until now. The other style -
- looks like this:
CLI::UI.frame_style = :bracket
CLI::UI::StdoutRouter.enable'Frame 1') do'Frame 2') { puts "inside frame 2" }
  puts "inside frame 1"

Frame Style

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| sleep(2.5) spinner.update_title('second round!') sleep (1.0) end sg.add('such spin') { sleep(1.6) } sg.add('many glyph') { sleep(2.0) } sg.wait end end 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' } sg.wait end


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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.