How to create a Ruby CLI app in a few easy steps

For our Module 1 capstone project at the Flatiron School, we were tasked with creating a CLI application with all CRUD operations (create, read, update, and delete) using Ruby and ActiveRecord. Having never built an app before, I was a bit nervous, but eventually found the process to help with my comprehension of Ruby and ActiveRecord and… dare I say… fun?

My partner and I were able to go from absolutely no idea what we were going to build nor how we would build it to MVP (Minimum Viable Product) in about 16 hours (split over the course of 2.5 days), then we took an additional 4–6 hours working on finishing touches and user interface design.

Having successfully completed the process, I want to share my experience and some pointers to save future novice coders some time (and headaches).

1. Choose a solid data source (or create one)

Since all apps need data in order to function, it’s a good idea to begin the preliminary work on your app with a search of API sources. Who wants to put in hours of work just to find that all those methods you wrote can’t function since there’s nothing to pass through them? And just because an API for the topic you’re exploring exists doesn’t mean you’ll want to use it. Look for one that’s readable, well-organized, and seems like something you would easily be able to pull the desired data from. Here’s a great resource for finding APIs.

If there’s no data source for your idea and the “realness” of your data isn’t all that important, try to use a Ruby gem called Faker. The type of data it can generate is somewhat limited (names, addresses, foods, comic book characters, cities, etc.), but it gets the job done if you’re in a crunch.

Lastly, if you’ve got the time, your needs are very specific, and quantity isn’t hugely important, seeding your own data is another option. This will definitely give you the most control over the specifics and quality of your data, but it may take awhile to build it out.

2. Have a clear plan

Although my partner and I did choose an app domain and function within about 30 minutes of being given the assignment, we didn’t set a clear plan until the following day. This was an intentional choice (kind of a “if there’s no plan, nothing can fail” sort of mindset), but it ultimately led to over 200 lines of unused code, some hair pulling, and fear of not completing the app in time. After correcting the initial error, this is what I found to be helpful:

• What’s the purpose of your app? Is the idea realistic? Will it help or entertain people? If it requires outside data to function, is there a good data source at your disposal? What are your current abilities as a coder?
• Think about your app from the user’s perspective. Is the idea something that someone would actually want to use? What sorts of functions and features would they expect? Is the app use intuitive?
• Organize, organize, organize. First, draw out your models and their relationships/associations on paper or a whiteboard. It’s incredibly important to be able to visualize what you’re building in real, physical terms. Next, organize your workspace. Although apps can be written using one main folder for all of your code, it’s best practice to use multiple folders so you’re forced to think about SRP (Single Responsibility Principle). For our app, we had folders for each of our three models with their own class and instance methods, a runner.rb file, which handled all of the user-facing methods, and a seeds.rb file, which contained our API source and a handful of other API-related methods. Choosing to organize the project in this way helped significantly.

3. Don’t bite off more than you can chew

As humans existing in 2020, we’ve all seen some incredible software and apps. Chances are, most of these programs were built by very skilled and experienced software engineers, so don’t feel bad about trying to stick to the basics. Learning how to code is a marathon, not a sprint. Don’t make your life unnecessarily difficult by choosing something that’s beyond your abilities.

If you find after a couple hours of working on your initial idea that your API isn’t going to function as you planned or that you’re not quite capable of writing the types of methods needed for your required functionality (yet), it may be best to go back to retool your plan or go back to the drawing board altogether and there’s no shame in that!

4. Test, test, test

It’s easy to fall into the trap of putting your head down with blinders on and writing method after method without fully testing your code, but as you already know, this can lead to some pretty frustrating errors! Make testing a part of the creation of your app from the very beginning.

• Test your API or other data source. Are you able to pull and filter the data in the way that you expected? Is the format you’re getting the data in how you need it? If not, see if you can retool your API pulling method. This is what our method ended up looking like:

Our API (National Parks Service) provided a hash of all national parks, forests, monuments, and historic sites, but we only needed the national parks. To achieve this, we added a simple “if” statement to filter by designation of the NPS site.

• Test your methods as you’re writing them. With every new method you write, you may be surfacing a bug in another method you weren’t aware of. Don’t try to push debugging until the very end! Just like with cooking, you may think it’s easier to push washing all the dishes until the end, but letting the dishes stack up is just going to make your life more difficult.
• Test your features. Sometimes your methods may perform as you expect when you test them in an isolated setting, but what about when you enter the CLI?

5. Let there be substance AND style

CLI apps are inherently simple looking, but that doesn’t mean they have to be boring! There are a lot of ways you can create a better user experience that don’t take all that much time, effort, or code, so stretch your skills and try a few!

• Give feedback to your users. Have you ever filled out a form online and didn’t receive some form of confirmation that the form had been submitted? It’s a bit scary! Don’t leave your users in the dark by not telling them whether they’ve successfully or unsuccessfully completed something. You can achieve this with a simple “if” statement using different interpolated string outputs, as you can see here in lives 31–34:

In this method, we told the customer that a tag they tried to create already existed if it was in our database or that the newly created tag had been successfully added to our database if it was new.

• Try TTY-Prompt. The most helpful tool we implemented is called TTY-Prompt, which allows app users to toggle up and down using the arrows on their keyboard and select a desired route. This eliminates the worry of a user typing in a character or word that can’t be computed in your method(s), then breaks your app. It did take us a bit of time to understand how to use the gem, but once it clicked, it made the build much easier and final product more user-friendly.

This is what our user prompt method ended up looking like after we fully implemented TTY-Prompt

• Try TTY-Font. After we’d completed all the functionality we needed from our app, we focused on aesthetics. A really simple way to make your app look better is to personalize your fonts. TTY-Font gives you the ability to do this easily and effectively.

You must use an Interface class to store all of our font and color formatting

• Try TTY-Color and Pastel. The last touch we added to our app was color. There are a lot of ways to colorize your text, but to keep things consistent, we chose TTY-Color and Pastel. These gems simply allow you to add color to specified lines of text.

Here’s the opening page of our app, MyParks Tagger

Check out all the other great TTY gems here.

Wrap-Up

I hope these tips and tricks I picked up help you build your own Ruby CLI app! Just remember to get organized, keep things real, spruce up your app, and — most importantly — have fun!