Getting Organized at the Command Line with WTF

Many people believe that getting organized involves a calendar, a todo list, or some arcane and complex mix of software. That’s one way to do the deed. It’s effective, but it’s not the most efficient way of doing things.

Instead, why not put everything under one roof? Or, in this case, into a single terminal window. How? By using a dashboard.

System administrators, DevOps engineers, and developers use dashboards to keep on top of what they need to keep on top of. Dashboards do that by breaking information into discrete chunks and displaying those chunks in their own spaces on screen. All that information is available at a glance and it’s easy to understand.

A dashboard isn’t just for the techie. Even if you have 10 thumbs when it comes to things technical, you can benefit from using a dashboard. I’m one of those folks with 10 thumbs, and I find dashboards to be very useful.

While I’m not a fan of its name, I am definitely a fan of what WTF does and how it does it. And that’s display a lot of different information in a way that’s clear and easy to follow.

Getting Started

It’s easy to install WTF. Download and unpack an archive, copy the executable (conveniently name wtf) somewhere in your path, and make it executable by typing chmod +x wtf.

WTF arranges different bits of information in a grid. Out of the box, that’s a two-by-two grid, which looks like this:

You can create a wider and deeper grid if you need WTF to display more information. Just remember that you might have to increase the size of your terminal window to see everything.

WTF’s default view isn’t going to help you much if you’re using the application to become more productive and organized. You’re not stuck with that. You can change what WTF shows you using modules.

Harnessing the Power of Modules

According to WTF’s developer, a module “is a discrete unit of functionality that extracts data from some source and packages that data for display.” The modules are very lightweight, and they’re easy to install. They’re text that you copy into WTF’s configuration file.

That file’s called config.yml and you can find it in the folder /.config/wtf in your /home directory. It’s a YAML (short for YAML Ain’t Markup Language) file, which contains information that humans and computers can easily read.

There are 38 modules (at least there were when I wrote this post) and they include a world clock, a todo list, one that displays tweets, and one that displays the weather. There are also modules that let system administrators, developers, and DevOps engineers interact with information from apps and services like GitLab, ZenDesk, Jira, Datadog.

Don’t think that WTF’s modules are strictly for techies. They aren’t. Anyone can use WTF to get and stay organized by using these modules:

• Todoist, which displays the popular web-based task management tool
• Todo, which creates a task list on your computer
• Trello, which displays information from the online project management application
• Google Calendar, which connects to Google’s online calendar
• Textfile, which displays the contents of one or more text files on your computer

To add a module to WTF, copy the code from the modules page on WTF’s website. Then, paste the code into the configuration file below the heading mods.

Each module has several configuration options. Some, like paths to files on your computer, are obvious. Others are specific to the module, like your access key and a project number for the Todoist module. When setting up WTF, check the documentation for the module that you’re adding for details about the properties.

A Trio of Potential Gotchas

There are three things you need to watch out for when adding modules. The first is to use spaces instead of tabs when indenting a module’s properties. If you don’t, WTF won’t start and spits out an error message like this:

Second, make sure that the modules and their properties are indented the correct number of spaces from the left margin. The name of the module should be four spaces from the left, and each property should be an additional two space in. If you don’t get the spacing right, WTF won’t start and you get the error message above.

Finally, you need to specify the correct position of a module in the grid. This is where things can get tricky.

Out of the box, WTF uses a grid that’s spans two columns — each is 40 characters wide and two rows 13 characters tall. You can change that by editing the grid property at the top of the configuration file.

grid:
	    columns: [40, 40]
	    rows: [13, 13, 4]

Each module has a position property, which looks something like this:

position:
	    top: 1
	    left: 0
	    height: 2
	    width: 1

In the default four-column grid, the example above puts a module on the top row of the column on the left.

As you add columns, you’ll need to fiddle with the positioning a bit. And don’t worry if the modules you add don’t display when you launch WTF. Chances are, they’re beyond the right and bottom edges of your terminal window. To check that, make your terminal window full screen. Then, edit the position in the configuration file.

Setting a module’s position sounds difficult, but it’s more fiddly work than anything else.

Working with WTF

Now that you’re set up, you can start using WTF. To do that, enter the command wtf in a terminal window. Here’s what my, admittedly simple, setup looks like:

If you’re wondering, I use the Clock, Textfile, Hackernews (a source of information for a news roundup I write), and Todo modules.

You can move between modules by pressing the Tab key on your keyboard. You can also interact with number of modules — like Todo, GitLab, Hacker News, and Textfile — while WTF is running.

Let’s say you’re using the Todo module. Tab over to it and then press n on your keyboard to create a task. Type the task, and press Enter to save it. To mark it as complete, scroll down in the list and press the Space bar on your keyboard.

If you need help with the functions available with a module, and their keyboard shortcuts, press the forward slash key (/) to open a help screen.

WTF takes a bit of work to set up. Once you’ve done that, it’s easy to use. If you use it properly, WTF can be a great tool to help keep you on track.

— Scott Nesbitt