Build CLIs that feel finished.

Quick start #

Register one command in your CLI. Require the command file, not the gem: it pulls in no emitter and no generator, so your CLI pays nothing at boot for a command that runs once per shell.

require "dry/cli/autocomplete/command"

module MyCLI
  extend Dry::CLI::Registry

  register "version", Version
  register "deploy", Deploy
  register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
end

Your users generate the script once and source it. Every completion it will ever offer is already inside, so pressing Tab spawns nothing and costs nothing.

mycli completion bash > /usr/local/etc/bash_completion.d/mycli

The command reads the program name from $PROGRAM_NAME. If your executable can run under another name, such as through a binstub, pin it:

register "completion", Dry::CLI::Autocomplete::Command[MyCLI, program_name: "mycli"]

Press TAB #

A shell with the mycli app from this page. Type part of a command and press Tab, or use the button. Switch the script off to see what the shell does without it.

The problem #

Your CLI knows its own commands, options, aliases and enum values. The shell does not. A dry-cli app with nested subcommands gives it nothing to work with, so mycli db <TAB> completes file names from the current directory, which is never what you wanted.

rngtng/dry-cli-completion already solves part of this, and it is worth reading first. It falls short in four ways, and each one is an acceptance criterion here.

A group with both a command and children loses the children

Register an overview command at a group's bare name so mycli db --help can explain the group, and its subcommands stop completing. This gem keeps both.

register "db", DbStatus         # the node now has a command
register "db migrate", Migrate  # ...and children, which never get walked

File arguments vanish

Completing a path is the single most common thing a user wants from a CLI. Here a file argument gets compgen -f in bash and _files in zsh.

The entry point is not free

Requiring a completion gem that loads its generator costs every invocation: 160ms for require "dry/cli" becomes 190ms. Here the command file loads nothing else until someone runs mycli completion.

zsh is a bashcompinit shim

zsh users deserve per-option descriptions. This gem prints a native #compdef script. It depends on dry-cli and dry-inflector, and nothing else.

What it generates #

Given this registry:

class Version < Dry::CLI::Command
  desc "Print the version"
  option :format, values: %w[json plain], desc: "Output format"
end

class Deploy < Dry::CLI::Command
  desc "Deploy the application"
  option :force, type: :boolean, aliases: ["-f"], desc: "Skip confirmation"
  argument :environment, values: %w[staging production], required: true, desc: "Target environment"
end

class DbStatus < Dry::CLI::Command
  desc "Show pending migrations"
  option :verbose, type: :boolean, desc: "Print full migration history"
end

class DbMigrate < Dry::CLI::Command
  desc "Run pending migrations"
  option :step, desc: "Migrate to a specific step"
  argument :file, desc: "Migration file to run"
end

register "version", Version
register "deploy", Deploy
register "db", DbStatus do |prefix|
  prefix.register "migrate", DbMigrate
end
register "secret", Secret, hidden: true

mycli completion bash prints a complete -F function. It finds the command path under the cursor, answers option values first, then offers that path's words:

_mycli_completions() {
  # ...walks COMP_WORDS to find the current command path...

  case "$path:$prev" in
    "version:--format") COMPREPLY=($(compgen -W "json plain" -- "$cur")); return ;;
  esac

  words=""
  case "$path" in
    "") words="version deploy db" ;;
    "version") words="--format" ;;
    "deploy") words="--force -f staging production" ;;
    "db") words="migrate --verbose" ;;
    "db migrate") words="--step" ;;
  esac

  COMPREPLY=($(compgen -W "$words" -- "$cur"))
  case "$path" in
    "db migrate") COMPREPLY+=($(compgen -f -- "$cur")) ;;
  esac
}
complete -F _mycli_completions mycli

What that output proves:

• db offers migrate alongside its own --verbose.
• db migrate gets real file completion.
• secret is absent, because hidden commands stay hidden.
• The -f alias on deploy is there because you declared it.
• mycli version --format <TAB> offers json plain, and nothing else.
• mycli deploy <TAB> offers staging production.

The script uses no associative arrays, so it runs under the bash 3.2 that macOS ships as /bin/bash.

mycli completion zsh prints a native script. Options go through _arguments with their desc as help text, subcommands through _describe, declared values become a value list, and file arguments use _files:

('deploy')
      _arguments -s \
        '--force[Skip confirmation]' \
        '-f[Skip confirmation]' \
        '*:Target environment:(staging production)' && ret=0
      ;;
    ('db')
      _arguments -s \
        '--verbose[Print full migration history]' && ret=0
      commands=(
        'migrate:Run pending migrations'
      )
      _describe -t commands 'db command' commands && ret=0
      ;;

Values and files #

Values declared on an option or argument come through at no cost:

option :format, values: %w[json yaml table]    # completes json yaml table after --format
argument :component, values: %w[major minor]   # completes major minor

An argument completes file paths when it declares file: true. Without that key, any argument whose name contains file or path is treated as one. Declare file: false to opt out of the guess:

argument :output, file: true     # completes paths
argument :path, file: false      # does not, despite the name
argument :config_file            # completes paths, by name

Shell function names derive from the program name: a program installed as my-tool gets _my_tool_completions in bash and _my_tool in zsh.

Installing the script #

The command takes one argument, bash or zsh, and prints the script to standard output. For bash:

# write it once
mycli completion bash > /usr/local/etc/bash_completion.d/mycli

# or evaluate it from .bashrc
eval "$(mycli completion bash)"

For zsh, where the script calls compdef to register itself:

# anywhere on your $fpath
mycli completion zsh > "${fpath[1]}/_mycli"

# or from .zshrc, after compinit
eval "$(mycli completion zsh)"

Regenerate it when you add or rename commands. Nothing watches for changes, by design.

Why the script is static #

Cobra and clap route every TAB press to a hidden __complete subcommand. That is the right call for a Go or Rust binary that starts in 10ms. It is the wrong call for Ruby:

Half a second of dead air per keystroke is unusable, and no amount of lazy loading gets under the host's own require cost. So there is no __complete command. The generator is not optimised either: at 0.067ms it is 0.01% of the cheapest possible invocation.

What it will not do #

• Values your host has to compute. The walk touches only objects dry-cli already holds. Declare values on the option, where dry-cli validates against them anyway.
• fish, PowerShell or nushell, yet. The emitter interface is built so a fourth shell is a new class.
• Watch your registry. Regenerating is your call, in your release process.

Quick start #

Require it after dry-cli. That alone changes every help screen in the process. Then make every setting once, in one block. Your registry, commands and options stay plain dry-cli, so you can add or remove the gem without touching a command.

require "dry/cli"
require "dry/cli/help"

Dry::CLI::Help.configure do
  title "MyCLI"

  description <<~TEXT
    Compile, validate, and evaluate rules.
  TEXT

  epilogue "Documentation: https://example.com/my-cli"

  color :auto
  width :terminal
  wrap true
end

module My
  module CLI
    extend Dry::CLI::Registry

    register "compile",  Compile
    register "validate", Validate
    register "evaluate", Evaluate
    register "version",  Version, aliases: ["--version", "-v"]
  end
end

$ my-cli -h
MyCLI
 
Compile, validate, and evaluate rules.
 
USAGE
  my-cli COMMAND [OPTIONS]
 
COMMANDS
  compile        Compile tax rules
  validate       Validate the rule corpus
  evaluate       Evaluate a tax return
  version        Show version
 
OPTIONS
  -h, --help     Show help
  -v, --version  Show version
 
Documentation: https://example.com/my-cli

A command reachable as --version lists under Options by its dashed names. Commands marked hidden: true stay out of every list, and a non-dashed alias prints next to its command, as in build, b.

Before and after #

The same command's help, from dry-cli alone and with require "dry/cli/help". Headings are bold and yellow, commands green, options and arguments cyan, and every description wraps to the terminal with a hanging indent.

$ my-cli compile -h
Command:
  my-cli compile
 
Usage:
  my-cli compile RULES [OUTPUT]
 
Description:
  Compile tax rules
 
Arguments:
  RULES                             # REQUIRED Rule file to compile
  OUTPUT                            # Where to write the compiled rules
 
Options:
  --format=VALUE, -f VALUE          # Output format: (json/yaml), default: "json"
  --[no-]strict                     # Treat warnings as errors
  --help, -h                        # Print this help

$ my-cli compile -h
USAGE
  my-cli compile RULES [OUTPUT] [OPTIONS]
 
DESCRIPTION
  Compile tax rules
 
ARGUMENTS
  RULES               Rule file to compile (required)
  OUTPUT              Where to write the compiled rules
 
OPTIONS
  -f, --format=VALUE  Output format (one of: json, yaml; default: "json")
  --[no-]strict       Treat warnings as errors
  -h, --help          Show help

The same comparison, as screenshots of examples/rbcheck

A whole tool #

examples/rbcheck in the gem's repository loads and configures dry-cli-help only when you pass --with-dry-cli-help, or -w, so you can run the same command both ways. Condensed:

#!/usr/bin/env ruby
require "dry/cli"

if [ARGV.delete("--with-dry-cli-help"), ARGV.delete("-w")].any?
  require "dry/cli/help"

  Dry::CLI::Help.configure do
    title "rbcheck"
    description "Small checks for Ruby projects."
    epilogue "Report bugs at https://example.com/rbcheck/issues"
  end
end

module Rbcheck
  extend Dry::CLI::Registry

  class Version < Dry::CLI::Command
    desc "Print the version"

    def call(**) = puts("rbcheck 1.0.0")
  end

  class CheckRubySyntax < Dry::CLI::Command
    desc "Check every Ruby file under a directory for syntax errors, and report "\
         "each file that fails to parse with its line number"

    argument :dir, desc: "Directory to scan", default: "."
    option :exclude, type: :array, desc: "Glob patterns to skip, such as vendor/**"
    option :quiet, type: :boolean, default: false, aliases: ["-q"],
           desc: "Print only the files that fail"

    example ["lib # check one directory", "--exclude=vendor/** # skip vendored gems"]

    def call(dir:, quiet:, exclude: [], **)
      # ... parses every file under dir with Prism ...
    end
  end

  register "version", Version, aliases: ["--version", "-v"]
  register "check-ruby-syntax", CheckRubySyntax
end

Dry::CLI.new(Rbcheck).call

rbcheck -h

dry-cli alone prints the list of commands to stderr, exits 1, and never wraps the long description:

$ rbcheck -h
Commands:
  rbcheck check-ruby-syntax [DIR]                 # Check every Ruby file under a directory for syntax errors, and report each file that fails to parse with its line number
  rbcheck version                                 # Print the version

With the gem, it prints to stdout and exits 0:

$ rbcheck -h --with-dry-cli-help
rbcheck
 
Small checks for Ruby projects.
 
USAGE
  rbcheck COMMAND [OPTIONS]
 
COMMANDS
  version            Print the version
  check-ruby-syntax  Check every Ruby file under a directory for syntax errors,
                     and report each file that fails to parse with its line
                     number
 
OPTIONS
  -h, --help         Show help
  -v, --version      Print the version
 
Report bugs at https://example.com/rbcheck/issues

• The title, description and epilogue come from the configure block.
• Commands list in the order they were registered, not alphabetically.
• The long description wraps under its own column.
• version is also reachable as --version and -v, so it lists under Options too.

rbcheck check-ruby-syntax -h

$ rbcheck check-ruby-syntax -h --with-dry-cli-help
USAGE
  rbcheck check-ruby-syntax [DIR] [OPTIONS]
 
DESCRIPTION
  Check every Ruby file under a directory for syntax errors, and report each
  file that fails to parse with its line number
 
ARGUMENTS
  DIR                         Directory to scan (default: ".")
 
OPTIONS
  --exclude=VALUE1,VALUE2,..  Glob patterns to skip, such as vendor/**
  -q, --[no-]quiet            Print only the files that fail (default: false)
  -h, --help                  Show help
 
EXAMPLES
  rbcheck check-ruby-syntax lib             check one directory
  rbcheck check-ruby-syntax --exclude=vendor/**
                                            skip vendored gems

• dry-cli's Command: section repeated the usage line, so it is gone, and the usage line shows the command takes options.
• The argument's default of "." shows up.
• Short aliases come first, and every description lines up in one column instead of trailing a #.
• Each example's comment moves into a column of its own, or onto the next line when the example is too long.

Settings #

A compact DSL in the spirit of dry-rb. Every setting validates its value and raises ArgumentError on one it cannot use.

color :auto honors NO_COLOR. width :terminal reads COLUMNS, then the console, then falls back to 80. A block that takes an argument receives the configuration instead of running against it:

Dry::CLI::Help.configure do |config|
  config.width = 100
  config.color = false
end

Dry::CLI::Help.config returns the current settings and Dry::CLI::Help.reset! forgets them all, which is handy between tests.

Exit codes

Running the program, or a group such as my-cli db, with no command prints its help to stderr and exits 1, as dry-cli does. With exit_code_without_arguments 0 it prints to stdout and exits 0 instead. -h and --help always print to stdout and exit 0. A mistyped command prints dry-cli's suggestion, then the help, to stderr and exits 1.

Headings, sections and groups #

Dry::CLI::Help.configure do
  heading :commands, "Available commands"

  group "Rules", "compile", "validate"
  group "Returns", "evaluate"

  hide :examples
  sections :banner, :usage, :commands, :options, :epilogue
end

• heading replaces one section's heading text: :usage, :description, :commands, :subcommands, :arguments, :options or :examples.
• group lists commands under a heading of their own, in the order given. A nested command is named by its full path, such as "db migrate".
• sections sets the order, and a section left out is hidden. hide hides sections without restating the order.

Every definition list on a screen shares one description column, never wider than half the wrap width, and text never wraps narrower than 20 columns.

Styles #

Every element's look is declared together, in one styles block. These are the defaults; name only the elements you want to change.

Dry::CLI::Help.configure do
  styles do
    title           :bold
    heading         :bold, :yellow, case: :UPPERCASE
    usage           :green
    command         :green
    argument        :cyan
    option          :cyan
    example         :green
    example_comment :bold, :black
  end
end

heading alone takes case:, one of :UPPERCASE, :Capitalize, :lowercase or :as_is, each written the way it cases.

The Colors module #

Every style is also available to your own commands:

class Deploy < Dry::CLI::Command
  include Dry::CLI::Help::Colors

  def call(**)
    puts green("Deployed.")
    puts red.bold("Rolled back.")
  end
end

The methods are the eight colors black red green yellow blue magenta cyan white, their bright_ forms, the on_ and on_bright_ backgrounds, and clear bold dim italic underline inverse hidden strikethrough. The colors come from pastel.

How it works #

The gem prepends one module to Dry::CLI, overriding the two private methods dry-cli prints help from. It does not replace Dry::CLI::Banner or Dry::CLI::Usage.

1. ARGV
2. Dry::CLI#call
3. #help --help on a command #spell_checker no command, a group, a typo
4. Screens::Command Screens::Listing
5. Formatter + Help.configure
6. stdout or stderr

Both methods are @api private in dry-cli, so a contract spec asserts every internal the gem reads. A dry-cli release that moves one fails the suite, naming what moved.

Quick start #

Include one module and the command gets a ui: in color and in place on a terminal, and as plain lines when the output is piped to a file or a CI log.

require "dry/cli"
require "dry-cli-ui"

class Import < Dry::CLI::Command
  include Dry::CLI::UI

  def call(**)
    ui.info "Importing tax rules..."

    rules = ui.spinner("Loading tax rules") { load_rules }

    ui.progress("Importing rules", total: rules.size) do |bar|
      rules.each do |rule|
        import(rule)
        bar.advance
      end
    end

    ui.success "Imported #{rules.size} rules"
  rescue => e
    ui.error("Import failed", e.message)
  end
end

On a terminal the spinner turns and the bar fills in place, with percent, count and ETA. Piped, and failing part way, the same command prints:

$ mycli import | cat
Loading tax rules...
✓ Loading tax rules (0.3s)
Importing rules...
𝘅 Importing rules 1482/1900 (4.1s)
 
┌─ Error ────────────────────────────────────────────────────────────────────┐
│                                                                            │
│  Import failed                                                             │
│                                                                            │
│  Could not validate rule US.2026.IRC.199A: missing dependency              │
│  taxable_income                                                            │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘

Include the module once in a base class and every command has ui. Including it loads nothing: the TTY gems load the first time ui is used.

class ApplicationCommand < Dry::CLI::Command
  include Dry::CLI::UI
end

class Import < ApplicationCommand
  def call(**) = ui.success("Nothing to import")
end

Dry::CLI::UI::Console needs nothing from dry-cli, so a Rake task or a plain script can use it too:

require "dry-cli-ui"

ui = Dry::CLI::UI::Console.new
ui.spinner("Compacting the database") { compact! }
ui.success "Done"

Watch a deploy #

One command, shown two ways: in a terminal, where spinners turn, bars fill in place and a status bar tracks the whole run; and piped to a file, where the same calls print plain lines a CI log can keep.

Press Run to start the deploy.

The command behind it:

class Deploy < Dry::CLI::Command
  include Dry::CLI::UI

  def call(**)
    ui.status_bar("deploy", hints: ["^C cancel"]) do
      assets = ui.spinner("Building assets") { build_assets }

      ui.multi_progress("Uploading", concurrent: 2) do |m|
        assets.each do |asset|
          m.progress(asset.name, total: asset.bytesize) do |bar|
            upload(asset) { |sent| bar.advance(sent) }
          end
        end
      end

      ui.multi_spinner("Warming caches") do |m|
        regions.each do |region|
          m.spinner(region) do |line|
            warm(region) { |host| line.detail = host }
          end
        end
      end
    end

    ui.success "Deployed #{assets.size} assets"
  rescue => e
    ui.error("Deploy failed", e.message)
  end
end

Real runs #

Not replays: recordings of the mycli app from the gem's examples folder, captured with asciinema. The text in each player is selectable: a recording is text, not video.

Downloading 64 IRS forms, six at a time

mycli download-urls -o irs-forms -p -c 6 -u irs.txt reads 64 PDF links from a file and downloads them into irs-forms/. Six download at once, each with its own bar, under a headline bar that counts all 64. When they are done, a box lists every file written. Recorded against dry-cli-ui's main branch, where -c is new since 0.5.0.

Hosted on asciinema.org.

Scanning the local network

mycli find-hosts -c 10 probes every address on the local /24 on the common TCP ports, ten addresses at a time, with one bar for addresses that answered and one for those that did not, then lists what it found. Recorded on a home network against dry-cli-ui's main branch.

Hosted on asciinema.org.

Messages and boxes #

Each level prints a blank line, then a box with the level's name as a colored title. Every argument is a paragraph, wrapped to fit. A popup draws over the screen, centred, and leaves the cursor where it was.

ui.debug   "Resolved 1900 rules from 14 files"
ui.info    "Importing tax rules..."
ui.success "Imported 1900 rules"
ui.warn    "3 rules have no effective date"
ui.error   "Import failed", e.message
ui.fatal   "Database unreachable"

ui.info "Short and narrow", width: 40
ui.box "Name: Alan Turing", "Role: Cryptanalyst", title: "Profile", width: 40
ui.box "Disk is 91% full", level: :warn, title: "Disk"
ui.popup "h  help", "q  quit", title: "Keys"

┌─ Profile ────────────────────────────┐
│                                      │
│  Name: Alan Turing                   │
│                                      │
│  Role: Cryptanalyst                  │
│                                      │
└──────────────────────────────────────┘

A status line is one line with a colored glyph, on the level's stream:

ui.status "Connected to the database", level: :success   # ✓ Connected to the database
ui.status "Disk nearly full", level: :warn               # ⚠ Disk nearly full
ui.status "Loaded", rules.size, "rules"                  # ℹ Loaded 1900 rules

Spinners #

A spinner returns its block's value and leaves ✓ Loading tax rules (0.3s) behind, or 𝘅 and the re-raised error. The block is given a Line: line.detail = redraws text after the label, and line.fail(reason) ends the spinner as failed without raising. Every Line method is thread-safe.

rules = ui.spinner("Loading tax rules") { load_rules }

ui.spinner("Importing rules") do |line|
  rules.each { |rule| line.detail = rule.name; import(rule) }
  line.fail("#{skipped.size} rules skipped") if skipped.any?
end

load = -> { YAML.load_file("rules.yml") }
rules = ui.spinner("Loading tax rules", &load)

Piped, each prints its label with ... when it starts, then its outcome:

Loading tax rules...
✓ Loading tax rules (0.3s)
Importing rules...
𝘅 Importing rules: 3 rules skipped (4.1s)

Progress bars #

The bar shows percent, current/total and ETA, and ends with a ✓ line. The block gets a handle with advance(step = 1), current and total, and color: paints one bar in any Pastel style.

ui.progress("Copying", total: files.sum(&:size)) do |bar|
  files.each do |file|
    copy(file) { |bytes| bar.advance(bytes) }
  end
  :copied                     # progress returns the block's value
end

Importing rules [◼◼◼◼◼◼    ] 61%  1159/1900  ETA 2.7s
✓ Importing rules 1900/1900 (4.2s)

Many jobs at once #

The block declares the jobs; they run once it returns, all at once by default or at most concurrent: n at a time. The call returns each job's value in declaration order. When a job raises, running jobs finish, the rest are skipped, and the first error is re-raised.

ui.multi_spinner("Fetching", concurrent: 2) do |m|
  m.spinner("fonts") { fetch(:fonts) }
  m.spinner("images") do |line|
    fetch(:images) { |done, all| line.detail = "#{done} of #{all}" }
  end
  m.spinner("video") { fetch(:video) }
end

[⠹] Fetching
├─ [⠹] fonts
├─ [⠹] images 12 of 40
└─ [ ] video

[𝘅] Fetching (0.5s)
├─ [✓] fonts (0.3s)
├─ [𝘅] images: 2 timed out (0.3s)
└─ [✓] video (0.2s)

multi_progress is the same shape with a bar per job and a headline bar that counts them all. Bars start and end in the same columns, and counts are right-aligned:

ui.multi_progress("Probing #{hosts.size} hosts") do |m|
  m.progress("Answered", total: hosts.size, color: :green) { |bar| ... }
  m.progress("No answer", total: hosts.size, color: :red) { |bar| ... }
end

[⠋] Downloading      [◼◼◼◼             ]  27%   66/240  ETA 2.1s
├─ [⠋] fonts.zip     [◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼ ]  95%    38/40  ETA 0.1s
├─ [⠋] images.tar.gz [◼◼◼              ]  23%   28/120  ETA 2.4s
└─ [ ] video.mp4

Task trees #

The block declares the tasks, so the tree is drawn complete before the first one starts. While it runs, every running task has its own spinner. concurrent: true runs a group's tasks at the same time. When a task raises, the rest are marked skipped and the error is re-raised.

ui.tasks("Deploy") do |t|
  t.task("Build assets") { build }
  t.group("Migrate") do |g|
    g.task("users") { migrate(:users) }
    g.task("orders") { migrate(:orders) }
  end
  t.group("Warm caches", concurrent: true) do |g|
    g.task("fonts") { warm(:fonts) }
    g.task("images") { warm(:images) }
  end
  t.task("Restart") { restart }
end

Deploy
├─ [✓] Build assets (0.4s)
├─ [✓] Migrate (0.3s)
│  ├─ [✓] users (0.1s)
│  └─ [✓] orders (0.2s)
├─ [✓] Warm caches (0.5s)
│  ├─ [✓] fonts (0.5s)
│  └─ [✓] images (0.3s)
└─ [✓] Restart (0.3s)

Deploy
├─ [✓] Build assets (0.4s)
├─ [▸] Migrate
│  ├─ [✓] users (0.1s)
│  └─ [𝘅] orders: table locked (0.2s)
├─ [▸] Warm caches
│  ├─ [✓] fonts (0.5s)
│  └─ [✓] images (0.3s)
└─ [✓] Restart (0.3s)

Status bar #

While its block runs, the bottom of the screen shows how the whole command is doing: what started last, how many things are running, done and failed, a bar over every progress bar, the elapsed time, and your hints. Nothing reports to it by hand. It sets no scroll region, so the scrollback keeps everything; piped, it just runs the block. The deploy demo above runs inside one.

ui.status_bar("deploy", hints: ["^C cancel"]) do
  ui.spinner("Building assets") { build }
  ui.multi_progress("Uploading", concurrent: 2) { |m| ... }
  ui.tasks("Migrate") { |t| ... }
end

Tables and prompts #

ui.table([["Alan Turing", 41], ["Ada Lovelace", 36]], header: %w[Name Age])

name = ui.prompt("Name?", default: "Alan Turing")
env  = ui.prompt("Environment?", choices: %w[staging production], default: "staging")
tier = ui.prompt("Tier?", choices: { "Free" => :free, "Pro" => :pro })
ui.confirm("Deploy to #{env}?", default: false)

┌──────────────┬─────┐
│ Name         │ Age │
├──────────────┼─────┤
│ Alan Turing  │ 41  │
│ Ada Lovelace │ 36  │
└──────────────┴─────┘

When standard input and err are terminals, prompts use arrow-key menus and line editing. Otherwise they read lines from standard input, so answers can be piped, and a list of choices is numbered:

$ printf 'production\ny\n' | mycli deploy
Environment?
  1) staging
  2) production
Choose 1-2 [staging]: 2
Deploy to production? (y/N) y

When the input runs out, a prompt returns its default, or raises Dry::CLI::UI::NonInteractiveError if it has none.

Where output goes #

So mycli export > rules.csv writes only the results to the file while progress stays on screen. A stream that is not a terminal, or runs under TERM=dumb, gets no animation and no escape codes. NO_COLOR turns color off and leaves animation on.

Configuration #

Spinners and bars look the same everywhere and are set once for the whole process. These are the defaults, plus a look of your own. An unknown name raises ArgumentError when it is set, and Dry::CLI::UI.reset! restores every default.

Dry::CLI::UI.configure do
  spinner_format :dots                                 # any TTY::Spinner format name
  bar_format(complete: "◼", incomplete: " ")           # or a TTY::ProgressBar format, such as :box
  bar_color :green                                     # the finished part: any Pastel style, or nil
  bar_background nil                                   # the whole bar: any Pastel style, or nil
end

Dry::CLI::UI.configure do |config|
  config.spinner_format = { interval: 8, frames: %w[◐ ◓ ◑ ◒] }
  config.bar_format = { complete: "#", incomplete: "." }
end

Override ui to configure the console for your commands:

class ApplicationCommand < Dry::CLI::Command
  include Dry::CLI::UI

  def ui
    @ui ||= Dry::CLI::UI::Console.new(
      out: out || $stdout,
      err: err || $stderr,
      box_width: 72,     # boxes are 72 columns rather than the whole terminal
      color: nil,        # true or false to override detection
      animate: nil       # true or false to override detection
    )
  end
end

Testing a command #

Pass StringIOs and assert on what was written. A StringIO is not a terminal, so the output is the plain form, with no escape codes.

out = StringIO.new
err = StringIO.new
ui  = Dry::CLI::UI::Console.new(out: out, err: err, input: StringIO.new("y\n"))

ui.spinner("Loading") { :ok }
ui.success "Imported"
ui.confirm("Continue?")        # => true

err.string   # => "Loading...\n✓ Loading (0.0s)\nContinue? (y/N) "
out.string   # => the Success box

RSpec.configure { |c| c.after { Dry::CLI::UI.reset! } }

Built on TTY Toolkit #

dry-cli-ui does not draw a single box or spinner frame by itself. The rendering comes from the TTY Toolkit by Piotr Murach, a collection of small, beautifully made terminal gems. dry-cli-ui decides what to show and when; these gems do the drawing. dry-cli-help colors its help screens with pastel, too.

• pastel terminal colors and styles
• tty-box framed boxes and popups
• tty-spinner spinners, single and many
• tty-progressbar progress bars with ETA
• tty-table tables
• tty-prompt menus and line editing
• tty-cursor cursor movement
• tty-screen terminal size
• strings wrapping and alignment

Thank you, Piotr. None of this would look half as good without your work.