Rugs on the Command Line

Scripting Automation

8 min readJan 19, 2017

At Atomist we designed Rug to automate all manner of tasks within and around software development. From generating new projects to upgrading libraries to refactoring code across multiple repositories to configuring CI, Rug allows you to describe, nay, capture your development process in code.

Once captured in generators and editors, collectively called Rugs, we want to make sure you can execute your Rugs in the right place at the right time. If you maintain an open source project, buttons may be the best fit for codifying a tutorial. If your team uses chat extensively, the Atomist bot might be the most comfortable interface for you. However, for many developers the command line is the most natural interface for interacting with and automating their tools.

Scripting common tasks in Bash or PowerShell is often a first step towards more complete automation. Shell scripting allows developers to quickly prototype in a language and runtime that is available for every modern platform.

At Atomist we are all about automating automation, so providing a way to interact with Rug on the command line was an absolute necessity. Enter the Rug CLI, a complete command-line interface for executing and developing Rugs.

This post will focus on getting started with the Rug CLI and using it to execute Rugs. A later post will describe how to use the Rug CLI to develop, test, and publish Rugs.

Installing the Rug CLI

We support installing the Rug CLI using common package tools for most platforms. On Mac OS X/macOS, you can install it using Homebrew:

$ brew tap atomist/tap
$ brew install rug-cli

More detailed instructions for installing the Rug CLI are available, including those for other platforms.

Once you have the Rug CLI installed, you can make sure it is working by running the following command:

$ rug --version
rug 0.21.0
atomist/rug-cli.git (git revision d6adaee; last commit 2017-01-18)

The version of the Rug CLI you installed may be different, but as long as you see output similar to that shown above, things are working.

We aim to support command-line interface standards like the —-help and ——version command-line options.

If you install the Rug CLI using the package tools on GNU/Linux and Mac and have Bash autocompletion configured properly, you will get proper autocompletion for rug in Bash as well.

Rug CLI Configuration

The first time you run the Rug CLI, it will create a .atomist directory in your home directory and create a default Rug CLI configuration file named cli.yml in that directory. The default contents of the Rug CLI configuration file suffice for all operations described in this introduction. We’ll talk more about configuring the CLI in the next post.

Searching for Rugs

Before we can execute Rugs on the command line, we need to know what Rugs are available to us. The Rug CLI has built-in support for searching for available Rugs using the search subcommand. Since we are not only interested in learning about the Rug CLI but also about Rug itself, let’s search for all Rugs tagged with rug. You can search for Rugs with specific tags using the -T command-line option.

What’s going on here? We asked the CLI to search for Rugs and we get a bunch of unrelated output. Well, the CLI is just keeping you informed of what it is doing. As mentioned above, the first time you run the CLI, it will create a default configuration for you; that’s the first line of output. Next, the CLI downloads all dependencies it needs to execute the Rug runtime. There are quite a few dependencies, so it may take a little time to download them. Don’t worry though, all the dependencies are cached locally in your ~/.atomist/repository directory, so subsequent invocations of the CLI will be faster.

Once the CLI is ready to do what you asked, it will issue a request to the Rug catalog and display the results. Here is what the entire output will look like in subsequent runs:

The output contains all Rug archives, a project that contains Rugs, that satisfy your search criteria.

Tip: running rug search without any other arguments will list all available Rug archives.

Describing Rugs

Now that we have a list of Rug archives that are tagged with rug, we need to decide which one we want to run. We may need more information to decide. The last line of output from rug search tells us how to get more information on the Rug archives: use the rug describe command. Since we want to learn about Rug, the rug-koans-project looks interesting. Let’s try describing it:

We see again that the Rug CLI first downloads what it needs to do what you ask it to. In this case, it downloads the archive you are asking it to describe and its dependencies. The rest of the output provides useful information about the Rug archive:

Its GitHub repository and the commit for this version
Where is it located locally, that is, where it was downloaded and cached
What Rugs are in it, a generator named NewRugKoansProject in this case
What version(s) of the Rug runtime it requires
What other Rug archives it depends on

The output ends with instructions on how to get more information. Let’s use that hint to get more information about NewRugKoansProject.

Other than some truly terrifying regular expressions used to validate parameter values (don’t fret, you understanding those regexes is not a prerequisite to using Rug!), we see that the NewRugKoansProject generator “creates a new Rug Koans project”, which stands to reason. It has a single tag, rug. It takes a single required parameter, project_name, and four optional parameters. Each parameter also has a plain-English name, a short description, and information on valid values (minimum & maximum length and the regular expression used for validation).

Once again, the last bit of the output gives us information on what we can do next: run the generator. Let’s look more closely at how we run this generator:

We use the generate subcommand [1] with the fully-qualified name of the generator [2], optionally specify the version [3] (the latest version is used if -a is not used), provide a name for our new project [4], and finally set values for the named parameters [5]. If you leave off some parameters, the CLI will tell you which are missing; or you can add the -I option to be prompted for them.

Running Rugs

Before we run the generator, let’s talk a bit about what a generator is. A Rug generator is used to create a new project from an existing model project. Rug generators are different from typical project templates in that they are a fully functioning project operating under native tooling: there are no special characters or constructs that disrupt compiling, testing, and running the model project using its native toolchain.

When we execute a generator using the Rug CLI, it’s going to create the new project in a new directory under the current one. Therefore we’ll run it from the directory where we have all our projects. Rather than supply the parameters on the command line, we will use the CLI’s interactive mode, invoked using the -I/——interactive command-line option. In this mode, you are prompted for each parameter value rather than having to supply them all on the command line. If you specify some parameter values on the command line when using interactive mode, the values you do specify will be the default value provided when the CLI prompts for that parameter.

The project name we provide is used as the name of the directory created to hold the project contents. The output from rug generate states that directory, rug-koans, was created with a few files we need to start using Rug koans to learn more about Rug. It also created a file named .atomist.yml which maintains a record of what Rugs have been run on this project. Let’s commit our initial version before we do anything else.

Now that we have our initial version committed, we can safely run some editors on our project. The rug-koans-project archive we described above only contained the generator we already ran. Looking at the other Rug archives listed in the search output above, the rug-koans-editors looks promising.

We again use the describe subcommand to learn more about the archive. This time we run the describe command without the -a/—-archive-version command-line option. When we do not specify a version, the Rug CLI determines the latest version and uses it.

The Step1 editor seems like a good place to start (or should it be Step0?). Let’s learn how to run it.

Since there are no parameters to this editor, we’ll just copy and paste that last line of the output to run the editor.

We see that running the editor created two files under the .atomist directory, overwrites the README with instructions for the first koan, and updates the .atomist.yml log. The files created under the .atomist directory are where the work for this koan needs to be done. Start with the test file, tests/Step1.rt. Instructions for what to do are in the file. More instructions and hints if you get stuck are in the README.

Now you can apply Rug editors to your own projects! If you have a Spring Boot project, check the editors available for that:

$ rug search -T spring-boot

If you don’t have a Spring Boot project, you can use the CLI to run the Spring Boot REST service generator.

Our next Rug CLI post will describe in detail how to use the Rug CLI to create, test, install, and publish Rugs. But don’t wait! You can continue with the remaining Rug koans editors to learn how to create your own Rugs right now.

To get more information about the Rug CLI, see its documentation. If you have questions, please join our Atomist community Slack and ask away! If you would like to learn more about using the Rug CLI and Atomist in your everyday work, please contact us. We hope you enjoy using Rugs and the Rug CLI to automate away your busy work!