Interstate CLI began on a whim, starting with my (Alec’s) recent conversion to Git from SVN. As you do, I started using Terminal so often that I couldn’t help but consider other tasks and ask whether they could be reasonably accomplished from the command line. This is not a new story, so I’ve gathered: this is why libraries like Thor, purpose-built for crafting shell scripts, exist in the first place.

We have happily discovered that, in fact, Interstate lends itself quite well to the command line. The Roadmap > Route > Road pathway is easily traversed with simple commands, and providing method options feels as natural here as it does in Git. 

Some aspects, however, needed reconsidering. For example, we made the choice to remove Interstates as the point of departure. In terms of navigating to a road, this works perfectly well with a mouse, but is slightly fatiguing on a keyboard. Instead, we’ve made roadmaps top-level, whereby typing “interstate maps” presents you with a list of roadmaps.

The second big thing was that we didn’t want to type either a 22 character identifier or the full title of whatever we were navigating to. The API doesn’t provide shortcodes, so we generate them locally. We’ve kept them short and easy to read: just one letter and two numbers. Finding what you want in a list is easy and the shortcode seems to stick in your mind quite easily.

Without further ado, here is what interstate-cli 0.0.4 can do so far:

interstate help

Show a list of tasks

interstate maps

Show a list of roadmaps associated with your API key

interstate map x##

Switch to a roadmap

interstate roads -r

Show a list of roads for the current roadmap. Because we have to cache the roads locally, occasionally run it with -r to see if you’ve got latest.

interstate road x##

Show a detail view of a road

interstate update x## -m -s

Update a road with optional —message (-m) and —status (-s) parameters. Note: the status parameter can take either a status code (1-14), the human readable status (e.g. “10%”, or “Started”), or if left blank, you’ll see a table of options and are prompted at that point.

interstate add -t -d

Add a road to the current roadmap with required —title (-t) and —description (-d) parameters.

interstate delete x##

Delete a road

interstate log

Display a log of recent activity for the current roadmap

interstate reset

Resets all interstate-cli local config 

Interstate-cli requires at least Ruby 1.87 and a reasonably current version of Rubygems. 

Install it with

sudo gem install interstate

You may need to install Apple’s developer tools on certain machines, although this issue is not currently reproducable and I haven’t had time to look into it in any depth. Also, some machines experience write permissions with certain interstate-cli config files. We are also looking into that.

For now, if you have problems setting it up, please email

Interstate-cli is by no means a finished product. If you like the concept and want to see it mature into a more useful, fully-rounded tool, please send us feedback! We see this as an experiment for now, but if it evolves into something bigger, that’s cool too!