How to add CLI to your own Ruby Gem and publish it!

In my latest article, I have talked about how to create a Ruby gem, you can read it from here. This time I would like to add our gem a CLI in order to run it from the command line and publish it on RubyGems.

Thor is a toolkit for building powerful command-line interfaces.

Thor is a gem useful for parsing arguments to your ruby CLI application. It creates documentation and does all the work about parsing user input under the hood so you don’t have to write repetitive if/else statements for possible different kinds of inputs.

Setup Thor

I’m going to use Thor on our gem created in a previous article here. But first, as you have might have guessed, we need to install Thor gem package in our system with gem install thor

Next, we should create a cli.rb file in lib/CheckParansfolder,

The first thing we do is requiring thor gem and CheckParans gem which we have created previously. Any methods defined under CLI class that inherits from Thor will be available as commands in our command line.

Next we need to create an executable file named bin/check_parans without any extension;

We should also add Thor as a dependency in check_parans.gemspec file. It will install Thor along with our gem if thor hasn’t installed before on our system.

spec.add_runtime_dependency 'thor'

So when we install the gem, we can run ruby on our command line, it will have check_parans method ready for us to use.

$ ruby -I lib bin/check_parans check_parans '()()()'
>true

There are many features in Thor that will make CLI better such as options, flags, subcommands and documentation. You can read more about it here.

PUBLISHING YOUR GEM

Now that we have created our gem, we are ready to share it! One could create gems for their own development workgroup and make it private or make it public so that everyone can use it. I believe the simplest way to distribute a gem for public use is to use RubyGems.org. As you probably already know, gems that are published to RubyGems.org can be installed by gem install command.

The first thing is first, you need to create an account on RubyGems.org, after creating your account, you can use your registered email and password when you push your gem. But make sure that in the gemspec file you have this config line;

spec.metadata["allowed_push_host"]="https://rubygems.org"

In this step, you may need to re-build your gem since we have changed the gemspec. You may also need to commit your changes before re-building your gem if you run into Gem::InvalidSpecificationException error.

Now we simple type gem push check_params-0.1.0.gem then enter our credentials to connect RubyGems.org

My first gem is published!

Now let's check RubyGems page for our gem;

one small step for man, one giant leap for mankind

Anybody can use this gem anywhere by adding gem "check_parans" inside project’s gemfile and addingrequire "check_parans" any file under the project root folder.

An Alternative Way

There is one more cool trick you might want to know about Bundler package manager, let’s say we didn’t publish our gem on RubyGems but we have a GitHub repository where our gem build is located at. ( Note that gemspec file must be present in this repository) We can do the following in our project’s gemfile.

gem "check_parans", :git => "git://github.com/kermit-klein/check_parans.git"

This will grab the gem through the Github repo, not RubyGems.org. Gems installed this way will not show up when you run gem list

Conclusion

There is not much to say about the process but it is due to the fact that it is quite simple to do! We had a brief overview of Thor’s functionalities and application after that I’ve shown how to publish Ruby gems via RubyGems.org. There are lots of information about handling and maintaining Ruby gems on RubyGems.org, for more detailed information I’d suggest you take a look at their documentation.