How to write your first CLI with Thor

At Magnetis we are moving our cloud infrastructure to Kubernetes. To do so I started creating a bunch of shell scripts inside our app. There is no problem with it, but as soon as i got 5 different shell script files it started to get messy.
In one of pair programming sessions that we do in our hiring process, a candidate chose Thor to write the test project. It was organized and seemed easy to get started. So connecting the dots I thought that our scripts probably would be much more expressive with Thor.
Command lines are already part of our everyday living: git, bundler and rails to name a few. Creating one helps you to organize and better share the utilities for daily work.
In this article we will write a simple example inspired by one of the best Breaking Bad scenes. But apart of its simplicity, it is the same process to create a CLI for really anything you want.

Creating a new gem

Let’s get started by creating a new gem, that will make it easier to distribute our software, in this case the executable file.
To create a new gem, bundler has a handy command (bundler itself is crafted with Thor):

$ bundle gem --exe walter
This will generate a skeleton as follows:
 create walter/Gemfile
 create walter/lib/walter.rb
 create walter/lib/walter/version.rb
 create walter/walter.gemspec
 create walter/Rakefile
 create walter/README.md
 create walter/bin/console
 create walter/bin/setup
 create walter/.gitignore
 create walter/.travis.yml
 create walter/.rspec
 create walter/spec/spec_helper.rb
 create walter/spec/walter_spec.rb
 create walter/LICENSE.txt
 create walter/exe/walter

Now we need to add the Thor as a dependency to our project, open up walter.gemspec and add:

spec.add_dependency "thor", "~> 0.20"

We will also need to remove the TODO items in the gemspec file, so go ahead and edit the values for summary, description and homepage. Run the bundle install command and it is all setup to write some Thor lines.
Enter Thor
Open up lib/walter.rb and let’s add some code, first thing you need to require and inherit from Thor:

require 'walter'
require 'thor'
module Walter
 class CLI < Thor
   # ...
 end
end

Now, let’s add a simple hello world:

class CLI < Thor
  desc "hello world", "my first cli yay"
  def hello
    puts "Hello world"
  end
end

Come on, hello world in 2017? Let’s make it a Hello Heisenberg!

class CLI < Thor
  desc "hello [name]", "say my name"
  def hello(name)
    if name == "Heisenberg"
      puts "you are goddman right"
    else
      puts "say my name"
    end
  end
end

We are almost there, last thing is to call our lib from the binary file.
The binary
The exe directive we used to create the gem, generated a walter binary at our project. First thing you need to do is to change the permissions so we can actually execute the file:

chmod +x exe/walter

Now, we are able to call it:

$ bundle exec exe/walter

This will give no output, but don’t worry. This is expected. Open up exe/walter in your favorite editor and let’s append this:

Walter::CLI.start(ARGV)

We are calling the CLI we just created, and passing the arguments received. Now let’s call it again:

$ bundle exec exe/walter
  walter hello [name]    # say hello
  walter help [COMMAND]  # Describe available commands or one specific command

Thor list all the commands this CLI has available, so sweet.
If you try to call our hello command without the name:

$ bundle exec exe/walter hello
ERROR: “walter hello was called with no arguments
Usage: “walter hello [name]”

Yeah, it tell us how to use it. Making this in shell script would require some conditionals, but Thor has this built-in.

$ bundle exec exe/walter hello Heisenberg
you are goddman right.

Installing and publishing

To install the gem to your system, this way you can it it from anywhere:

$ rake install 

Call it:

$ walter hello Jesse
say my name

If you want to release it to rubygems, just run:

$ rake release

The Ruby ecosystem is beautiful, isn’t it?

Conclusion

Thor makes daily scripts much more expressive and meaningful. It is a nice addition to a team that is already using Ruby as an official language, since all the team members can contribute to make your commands even better.
In our case, it was used to create commands to bring up kubernetes clusters and to deploy our app for the staging environment. You can use to automate some internal process or workflow you have in your company!
To finish this up, some final tips:

• whenever possible try to use command methods that are common to other CLIs: init, status, new, create, update.
• try to expose as CLI the least amount of methods possible, so you can encapsulate things that are only needed inside the code.
• if you need to write some config file use $HOME/.<yourcli>

If you want to go deeper into the subject, here are the official docs.
Happy Thor!

Previously posted at medium