Writing Command-Line Utilities with Dart

by Monty Rasmussen

If there's one thing computers are good for, it's automating repetitive, tedious startup or maintenance tasks that waste developers' time and, in the worst cases, serve as a deterrent to starting a project at all. Writing a few small scripts to handle the boilerplate and scaffolding can go a long way toward eliminating barriers to productivity. For modern web developers, some common technologies for adding custom tools to the tool belt are Perl (for old-school scripters) and Node.js (using JavaScript).

Dart is a newer language, originally developed by Google but now an ECMA standard, for building web, server, command-line, and mobile apps. It's a scalable, object-oriented programming language, with robust libraries and runtimes included out of the box. In this tutorial, we'll go over how you can get set up to write your own command-line utilities with Dart.

Check out the Dart Language Tour for a crash course in the language, or take a look at the FAQ for a higher-level overview. If you know JavaScript, Java, PHP, ActionScript, C/C++, or another "curly brace" language, you'll find Dart to be familiar.

Tested with Dart SDK version v2.0.0.

Environment Setup

Let's take a quick look at the technologies you'll be using for this project. If you're missing any of them, you'll need to follow the instructions to get them installed.

Dart

Dart is an open-source, scalable, object-oriented programming language, with robust libraries and runtimes, for building web, server, and mobile apps. It was originally developed by Google, but has since become an ECMA standard.

Dart Primers

Check out the Dart Language Tour for a crash course in the Dart language. If you already know JavaScript, Java, PHP, ActionScript, C/C++/C#, or another "curly brace" language, you'll find Dart to be familiar, and you can be productive with Dart within an hour or so.

If you like learning from videos, take a look at Learn Dart in One Video.

Get Dart

Before you can get into the exciting world of writing Dart code, you need to download the Dart SDK:

Dart Tools and IDEs

For ideas on what editor you should use to work on a Dart project, or to learn more about Dart's awesome suite of developer tools, check out the Dart Tools page. Note that since you need to import external libraries for this project, you will not be able to use the online DartPad environment.

Note: Many sections of this article will describe steps and tasks in terms of using WebStorm, but if you're using another environment, it should be easy to translate these passages into those suitable for your use case.

System Path

For the first part of this tutorial, you'll run your command-line application using Pub, which is Dart's tool for managing packages, assets, and dependencies, and also includes commands for creating, developing, deploying, and executing Dart applications. To make life easy for yourself, you'll want to add dart-sdk/bin to your system's PATH environment variable so you can access Pub from anywhere in your terminal.

On your system's command line, use the appropriate command for your operating system, inserting the path to your Dart SDK where indicated.

Windows (assuming the C: drive):

> set PATH=%PATH%;C:\\bin

Mac OS:

$ export PATH=$PATH:/bin

Linux:

$ export PATH=${PATH}:/bin

Additionally, it can be beneficial to add Pub's cache location to your system path, as this is where globally installed Dart scripts will end up:

Windows: %APPDATA%\Pub\Cache\bin

Mac OS or Linux: ~/.pub-cache/bin

You can read more about these paths in the official docs.

Create a New Project

Once you've got the Dart SDK and an editor downloaded and installed, it's time to create a new project. You can use Stagehand on the command line, or if you're using WebStorm, the editor can automate the process for you via the menu: File->New->Project.

WebStorm uses Stagehand behind the scenes to create projects, so either way you do it, you'll want to create a Console application. Go ahead and name the project boilerplate. You will want to be sure to use the Generate sample content option (on by default for projects created with the Stagehand command-line utility).

Get Dependencies

WebStorm will automatically open the new project and get all needed dependencies. If you're using something else, you may need to acquire your project's dependencies manually by opening a terminal on the project root and typing:

pub get

Hello, World

In WebStorm, your project should start with two files open in the editor: pubspec.yaml and main.dart (if not, open them now by double-clicking each of them in the Project panel). Dart uses your pubspec file to manage your project's dependencies, and main.dart will be your primary code file.

To keep things simple, remove all of the pre-generated code from your main.dart file and replace it with this:

void main(List arguments) {  
  print("Hello, World!");
}

All Dart programs start execution with the main() function. In this code, we make use of Dart's optional type annotations to make things clearer and improve tooling. void indicates that main() will return nothing (null), and List arguments tells the Dart VM that if there are any command-line arguments passed to our application, they should be accessible in arguments, which is a List (Dart's array type) of elements of type String. The body of the function has just one line, which synchronously prints the string "Hello, World!" to the system console.

Run the code in main.dart by right-clicking the file in the Project panel and selecting Run, or you can use the hotkey Shift+F10 if main.dart is selected. Console output will appear in the Run panel, which displays by default in the lower portion of the WebStorm interface.

Hello, World!

Pub Global

Dart's Pub program is a versatile tool. You can use the global command to activate Dart packages, which allows you to use Pub in the system terminal to run scripts from that package's bin directory. (Note: A package is Dart's largest unit of modularity for sharing code, and every Dart application with a pubspec.yaml file in its root directory is also a package.) It's possible to activate a Dart package housed on pub.dartlang.org or from a Git repository, but for this tutorial you'll activate the package right from the local machine.

pub global activate --source path

Enter the above command on your system's terminal, inserting the absolute or relative path to your boilerplate project.

Note: If you run the command from your project's root directory, you can specify a path of ., meaning "current path."

WebStorm provides a convenient way to access a terminal with its Terminal panel. You can bring up that panel with the application's menu: View->Tool Windows->Terminal. Alternatively, use the hotkey Alt+F12. If you've correctly updated your system path to include the Dart SDK, Pub will be globally accessible in your terminal.

Pub's response should look something like:

Activated boilerplate 0.0.1 at path "".

That done, you can now use pub run in combination with pub global to run the main.dart script from anywhere, using a command with the form:

pub global run :