Building Your first Command Line Application in Ruby

If you have Ruby installed on your computer and you’d like to get a little bit of practice coding, this article will run you through creating your very first Command Line Interface in Ruby.

Assumptions:

This article is not for everyone! It’s for people with some experience of coding. To make this accessible without being unreasonably long it assumes that:

• You have Ruby and Git installed on your computer

• You know how to open a terminal window using your operating system

• You’re using a terminal that allows for Unix (not windows) commands

• You have the ability to fire off a text editor from the command line

I wrote If any of these things aren’t true, keep an eye out for a future article where I’ll run you through the basics of setting up a professional software development environment on your computer.

The Power of the Command Line Interface (CLI)

Once you start on the path to becoming a professional software developer, you’re going to learn to love the terminal window. The terminal is how you connect to programs that expose a Command Line Interface (CLI). A CLI is simply a way of “talking” to a piece of software by passing it text commands.

The terminal is the place where you can tell your computer exactly what you want it to do without having to test your hand-eye coordination with a mouse a bunch of times just to find the menu option you’re interested in! In fact, the more time you spend programming, the more likely you are to start to use text based interfaces for interacting with computers. It’s one of the reasons that text editors like vim and emacs continue to be popular amongst developers.

There are lots of cool things you can build a command line app to do – whether you want to be able to check the weather, back up your files to a remote location or write scripts to automate “busywork” like pulling information out of an excel file. In this article, we’re just going to hit the basics – how do you create and run a Ruby program that can take input from and provide output to your terminal window. In a future article we’ll add some more functionality to show just how powerful a CLI can be.

Building a CLI in Ruby

Assuming you have Ruby installed, creating a command line interface is pretty straightforward. In this article, I’m going to keep track of my changes using Git for version control. It’s not required, but if you ever want to become a professional software developer, it’s a skill you should practice.

Start by opening a terminal window on your machine. Then I’m going to start by going to the directory I keep all of my code in. You should go to a directory within your home directory on your computer so you have permission to write and edit files.  Note that I’m using unix style commands – these will work on any variety of Unix, on a Mac or a Windows machine as long as you use something like the Windows Subsystem for Linux. 

> cd code

Next up we want to create a new directory that we’ll use to keep any files we create. Let’s call the directory “my-first-cli” and get Git to create it for us:

> git init my-first-cli
> cd my-first-cli

OK, now let’s open a text editor. I’m going to use Visual Studio Code and I’ve configured it so I can start it from the command line. 

> code .

OK, now let’s create a file – for now let's just call it cli.rb, and let’s put the following code into it to get us the simplest possible CLI application.

> #!/usr/bin/env ruby
> puts 'hello world'

Now, let’s save the file to disk – typically hitting the S key while holding down the command key on a mac or the control key on a PC. And then let’s save our changes in Git

> git add .
> git commit -m “Simplest possible CLI”

OK, let’s see what we’ve got. Firstly, we need to make the file executable, so type:

> chmod +x cli.rb

And then try running the file (note the preceding `./` – you’ll need that to make this work)

> ./cli.rb
hello world

Yay! We’ve created a hello world CLI! 

There are two lines of code. The `puts` is just a way to send a string to the standard output (in this case, the terminal window from which you called the app). And the first line is a “shebang” which tells the computer what interpreter to use to process the rest of the file – in this case, Ruby. We could change that to something like `#!/usr/bin/env python` if we wanted to write a Python script – but let’s save that for a different tutorial!

OK, so we have a script that we can call that outputs to the command line. Now let’s see if we can take an input from the CLI as well. Let’s personalize the greeting to make it “hello Sarah” – replacing Sarah with whatever name we pass into the script.

Let’s use the OptionParser class which is built right into Ruby. It allows us to parse any options provided from the command line and can even create help docs for your script.

Let’s start by putting the following into the cli.rb so it looks like:

#ruby
#!/usr/bin/env ruby
require 'optparse'
options = {}
OptionParser.new do |parser|
  parser.on("-n", "--name NAME", "The name of the person") do |value|
      options[:name] = value
    end=
  end.parse!
  puts 'hello ' + options[:name]

What are we doing here? After the shebang, we’re telling Ruby we want to use the optparse class, and then we’re cutting and pasting a tweaked version of the “minimal example” from the docs for optparse to parse a name option and set that to a variable.

Try it out! Save the changes to the file, and then from the terminal window run:

> ./cli.rb --name Sam

And you should see the output “hello Sam”!

But now let’s just try it without the name and check it still works . . .

> ./cli.rb

Hmmm, I get:

Traceback (most recent call last):
1: from ./cli.rb:12:in `<main>'
./cli.rb:12:in `+': no implicit conversion of nil into String (TypeError)

So it’s complaining that I’m trying to use a “name” key in the options hash, but I don’t have the key. There are lots of ways to fix this, but a quick one might be:

#ruby
#!/usr/bin/env ruby
require 'optparse'
options = {}
OptionParser.new do |parser|
    parser.on("-n", "--name NAME", "The name of the person") do |value|
        options[:name] = value
    end
  end.parse!
 if options[:name]
     puts 'hello ' + options[:name]
  else
    puts 'hello stranger'
  end

Now try calling this both with a name:

> ./cli.rb --name Sam
hello Sam

and without one:

> ./cli.rb
hello stranger

Great! Let’s remember to save our changes to version control:

> git commit -am "CLI takes a name"

And there we go! We’ve now created a super simple CLI program in Ruby.

Disclaimer: The information in this blog is current as of August 30, 2019. Current policies, offerings, procedures, and programs may differ.