Thor is a CLI building tool for Ruby. It is a more robust solution than the built-in optparse module and is more appropriate for larger scripts with multiple commands or subcommands.
I intend for this post to primarily augment the document on the Thor website. There are several features of Thor that are not documented on the site that I find useful in day-to-day use.
Quick start
Following is a simple example of a CLI application built using Thor. It has one command hello that, greets the user.
# example taken from whatisthor.com
require "thor"
class MyCLI < Thor
desc "hello NAME", "say hello to NAME"
def hello(name)
puts "Hello #{name}"
end
end
MyCLI.start(ARGV)
Exit on failure
If you run the program in the [[#Quick start]] without providing a name, you will get the following output, and the exit status will be 0.
ERROR: "cli.rb hello" was called with no arguments
Usage: "cli.rb hello NAME"
Deprecation warning: Thor exit with status 0 on errors. To keep this behavior, you must define `exit_on_failure?` in `MyCLI`
You can silence deprecations warning by setting the environment variable THOR_SILENCE_DEPRECATION.
To get rid of the warning, add an exit_on_failure? static method to your class.
class MyCLI < Thor
def self.exit_on_failure?
true
end
# ...
end
If the value returned is true, you will get an exit status of 1 on error. If it is false, you will get an exit status of 0. I will always set this to true because it will work as expected in shell scripts, and it does not have a meaningful impact when calling it directly from a terminal barring any personalization that deals with exit values.
Options
You can add options by specifying option metadata like the following:
# example taken from whatisthor.com
require "thor"
class MyCLI < Thor
desc "hello NAME", "say hello to NAME"
option :from
def hello(name)
puts "from: #{options[:from]}" if options[:from]
puts "Hello #{name}"
end
end
MyCLI.start(ARGV)
## Example usage
#
# > `ruby ./cli.rb hello --from Fred Wilma`
# from: Fred
# Hello Wilma
Configuring options
There are several parameters you can use to configure an option. The ones I use the most are required, default, type, alias, and desc. Here is an extension of the example above.
require "thor"
class MyCLI < Thor
desc "hello NAME", "say hello to NAME"
option :from, default: "your secret admirer", desc: "Who is doing the greeting", aliases: [:f]
def hello(name)
puts "from: #{options[:from]}"
puts "Hello #{name}"
end
end
Note that we drop the if from the line where we print the from:. Since the from option provides a default, it will always have a value. Since we provide an alias (:f), we can invoke the program like ruby ./cli.rb hello -f Fred Wilma and get the same result.
Options are strings by default, but can be one of several types.
Note that you can also defined an option at the class level, and it will apply to all methods in the class.
Enums
One particular configuration option I would like to point out is enum. I often write scripts that have an option where the value belongs to a list of acceptable values, such as environment for running software.
Following is an example of a CLI that requires an environment option to be one of local, testing, or production.
class MyCLI < Thor
def self.exit_on_failure?
true
end
desc "reset-db", "Reset the database"
option :environment, desc: "The env for the db", default: "local", enum: %w[local testing production], aliases: :e
def reset_db
puts "Resetting the database in the #{options[:environment]} environment..."
# ...
end
end
## Example usage
#
# > ruby ./cli.rb reset-db
# Resetting the database in the local environment...
#
# > ruby ./cli.rb reset-db -e testing
# Resetting the database in the testing environment...
#
# > ruby ./cli.rb reset-db -e other
# Expected '--environment' to be one of local, testing, production; got other
Note that the help includes the values as well.
> ruby ./cli.rb help reset-db
Usage:
cli.rb reset-db
Options:
-e, [--environment=ENVIRONMENT] # The env for the db
# Default: local
# Possible values: local, testing, production
Reset the database
Setting the default command
Note that most of the examples in this post are applications with only one command. It is possible by specifying the default_command on the class.
class MyCLI < Thor
default_command :hello
desc "hello", "say hello"
option :name, required: true
def hello
puts "Hello #{options[:name]}"
end
end
## Example usage
#
# > ruby ./cli.rb --name Wilma
# Hello Wilma
The catch is that this does not work well if the default command requires arguments. Consider the following example.
class MyCLI < Thor
default_command :hello
def self.exit_on_failure?
true
end
desc "hello NAME", "say hello to NAME"
option :from
def hello(name)
puts "from: #{options[:from]}" if options[:from]
puts "Hello #{name}"
end
end
Note that NAME is a required argument.
If we run this without specifying the command and providing the name, we get the following.
> ruby ./cli.rb Wilma
Could not find command "Wilma".
However, if we specify the :from option, we get a different result.
> ruby ./cli.rb --from Fred Wilma
from: Fred
Hello Wilma
This makes sense because Thor can tell based on the option that we are not specifying a command. However, when we do not have an option, it cannot tell the difference between a command and an argument.
I think a reasonable rule of thumb is that if you set a default command, it should not have arguments. Any configuration should be presented as options, some of which may be required.
]]>
