Run external commands with pretty output logging and capture stdout, stderr and exit status. Redirect stdin, stdout and stderr of each command to a file or a string.
TTY::Command provides independent command execution component for TTY toolkit.
Complex software projects aren't just a single app. These projects usually spawn dozens or hundreds of supplementary standalone scripts which are just as important as the app itself. Examples include - data validation, deployment, monitoring, database maintenance, backup & restore, configuration management, crawling, ETL, analytics, log file processing, custom reports, etc. One of the contributors to TTY::Command counted 222 scripts in the bin directory for his startup.
Why should we be handcuffed to sh or bash for these scripts when we could be using Ruby? Ruby is easier to write and more fun, and we gain a lot by using a better language. It's nice for everyone to just use Ruby everywhere.
TTY::Command tries to add value in other ways. It'll halt automatically if a command fails. It's easy to get verbose or quiet output as appropriate, or even capture output and parse it with Ruby. Escaping arguments is a breeze. These are all areas where traditional shell scripts tend to fall flat.
Add this line to your application's Gemfile:
gem 'tty-command'And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-command
Create a command instance and then run some commands:
cmd = TTY::Command.new
cmd.run('ls -la')
cmd.run('echo Hello!')Note that run will throw an exception if the command fails. This is already an improvement over ordinary shell scripts, which just keep on going when things go bad. That usually makes things worse.
You can use the return value to capture stdout and stderr:
out, err = cmd.run('cat ~/.bashrc | grep alias')Instead of using a plain old string, you can break up the arguments and they'll get escaped if necessary:
path = "hello world"
FileUtils.touch(path)
cmd.run("sum #{path}") # this will fail due to bad escaping
cmd.run("sum", path) # this gets escaped automaticallyRun starts the specified command and waits for it to complete.
The argument signature of run is as follows:
run([env], command, [argv1, ...], [options])
The env, command and options arguments are described in the following sections.
For example, to display file contents:
cmd.run('cat file.txt')If the command succeeds, a TTY::Command::Result is returned that records stdout and stderr:
out, err = cmd.run('date')
puts "The date is #{out}"
# => "The date is Tue 10 May 2016 22:30:15 BST\n"If the command fails (with a non-zero exit code), a TTY::Command::ExitError is raised. The ExitError message will include:
- the name of command executed
- the exit status
- stdout bytes
- stderr bytes
If the error output is very long, the stderr may contain only a prefix, number of omitted bytes and suffix.
If you expect a command to fail occasionally, use run! instead. Then you can detect failures and respond appropriately. For example:
if cmd.run!('which xyzzy').failure?
cmd.run('brew install xyzzy')
endTo simulate classic bash test command you case use test method with expression to check as a first argument:
if cmd.test '-e /etc/passwd'
puts "Sweet..."
else
puts "Ohh no! Where is it?"
exit 1
endBy default, when a command is run, the command and the output are printed to stdout using the :pretty printer. If you wish to change printer you can do so by passing a :printer option:
:null- no output:pretty- colorful output:progress- minimal output with green dot for success and F for failure:quiet- only output actual command stdout and stderr
like so:
cmd = TTY::Command.new(printer: :progress)By default the printers log to stdout but this can be changed by passing an object that responds to << message:
logger = Logger.new('dev.log')
cmd = TTY::Command.new(output: logger)You can force the printer to always in print in color by passing the :color option:
cmd = TTY::Command.new(color: true)Sometimes it can be useful to put your script into a "dry run" mode that prints commands without actually running them. To simulate execution of the command use the :dry_run option:
cmd = TTY::Command.new(dry_run: true)
cmd.run(:rm, 'all_my_files')
# => [123abc] (dry run) rm all_my_filesTo check what mode the command is in use the dry_run? query helper:
cmd.dry_run? # => trueIn order to run a command with Ruby interpreter do:
cmd.ruby %q{-e "puts 'Hello world'"}The environment variables need to be provided as hash entries, that can be set directly as a first argument:
cmd.run({'RAILS_ENV' => 'PRODUCTION'}, :rails, 'server')or as an option with :env key:
cmd.run(:rails, 'server', env: {rails_env: :production})When a value in env is nil, the variable is unset in the child process:
cmd.run(:echo, 'hello', env: {foo: 'bar', baz: nil})When a hash is given in the last argument (options), it allows to specify a current directory, umask, user, group and and zero or more fd redirects for the child process.
To change directory in which the command is run pass the :chidir option:
cmd.run(:echo, 'hello', chdir: '/var/tmp')There are few ways you can redirect commands output.
You can directly use shell redirection facility like so:
cmd.run("ls 1&>2")You can provide the streams as additional hash options where the key is one of :in, :out, :err, an integer (a file descriptor for the child process), an IO or array. The pair value can be a filename for redirection.
cmd.run(:ls, :in => "/dev/null") # read mode
cmd.run(:ls, :out => "/dev/null") # write mode
cmd.run(:ls, :err => "log") # write mode
cmd.run(:ls, [:out, :err] => "/dev/null") # write mode
cmd.run(:ls, 3 => "/dev/null") # read modeYou can also provide actual file descriptor for redirection:
cmd.run(:cat, :in => open('/etc/passwd'))For example, to merge stderr into stdout you would do:
cmd.run(:ls, '-la', :stderr => :stdout)
cmd.run(:ls, '-la', 2 => 1)You can pass input via the :in option, by passing a StringIO Object. This object might have more than one line, if the executed command reads more than once from STDIN.
Assume you have run a program, that first asks for your email address and then for a password:
in_stream = StringIO.new
in_stream.puts "[email protected]"
in_stream.puts "password"
in_stream.rewind
TTY::Command.new.run("my_cli_program", "login", in: in_stream).outYou can timeout command execuation by providing the :timeout option in seconds:
cmd.run("while test 1; sleep 1; done", timeout: 5)Please run examples/timeout.rb to see timeout in action.
To run command as a given user do:
cmd.run(:echo, 'hello', user: 'piotr')To run command as part of group do:
cmd.run(:echo, 'hello', group: 'devs')To run command with umask do:
cmd.run(:echo, 'hello', umask: '007')Each time you run command the stdout and stderr are captured and return as result. The result can be examined directly by casting it to tuple:
out, err = cmd.run(:echo, 'Hello')However, if you want to you can defer reading:
result = cmd.run(:echo, 'Hello')
result.out
result.errTo check if command exited successfully use success?:
result = cmd.run(:echo, 'Hello')
result.success? # => trueTo check if command exited unsuccessfully use failure? or failed?:
result = cmd.run(:echo, 'Hello')
result.failure? # => false
result.failed? # => falseTo check if command ran to completion use exited? or complete?:
result = cmd.run(:echo, 'Hello')
result.exited? # => true
result.complete? # => trueThe result itself is an enumerable and allows you to iterate over the stdout output:
result = cmd.run(:ls, '-1')
result.each { |line| puts line }
# =>
# CHANGELOG.md
# CODE_OF_CONDUCT.md
# Gemfile
# Gemfile.lock
# ...
# lib
# pkg
# spec
# tasksBy default the linefeed character \n is used as a delimiter but this can be changed either globally by calling record_separator:
TTY::Command.record_separator = "\n\r"or configured per each call by passing delimiter as an argument:
cmd.run(:ls, '-1').each("\t") { ... }If the built-in printers do not meet your requirements you can create your own. At the very minimum you need to specify the write method that will be called during the lifecycle of command execution:
CustomPrinter < TTY::Command::Printers::Abstract
def write(message)
puts message
end
end
printer = CustomPrinter
cmd = TTY::Command.new(printer: printer)Here's a slightly more elaborate example to illustrate how tty-command can improve on plain old shell scripts. This example installs a new version of Ruby on an Ubuntu machine.
cmd = TTY::Command.new
# dependencies
cmd.run "apt-get -y install build-essential checkinstall"
# fetch ruby if necessary
if !File.exists?("ruby-2.3.0.tar.gz")
puts "Downloading..."
cmd.run "wget http://ftp.ruby-lang.org/pub/ruby/2.3/ruby-2.3.0.tar.gz"
cmd.run "tar xvzf ruby-2.3.0.tar.gz"
end
# now install
Dir.chdir("ruby-2.3.0") do
puts "Building..."
cmd.run "./configure --prefix=/usr/local"
cmd.run "make"
endAfter checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-command. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Copyright (c) 2016-2017 Piotr Murach. See LICENSE for further details.