update the readme
diff --git a/README.md b/README.md
index bf2dcf9..e27d663 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 [![Build Status](https://travis-ci.org/dart-lang/cli_util.svg)](https://travis-ci.org/dart-lang/cli_util)
 
-## Usage
+## Locating the Dart SDK
 
 ```dart
 import 'dart:io';
@@ -26,6 +26,38 @@
 }
 ```
 
+## Displaying output and progress
+
+`package:cli_util` can also be used to help CLI tools display output and progress.
+It has a logging mechanism which can help differentiate between regular tool
+output and error messages, and can facilitate having a more verbose (`-v`) mode for
+output.
+
+In addition, it can display an indeterminate progress spinner for longer running
+tasks, and optionally display the elapsed time when finished: 
+
+```dart
+import 'package:cli_util/cli_logging.dart';
+
+main(List<String> args) async {
+  bool verbose = args.contains('-v');
+  Logger logger = verbose ? new Logger.verbose() : new Logger.standard();
+
+  logger.stdout('Hello world!');
+  logger.trace('message 1');
+  await new Future.delayed(new Duration(milliseconds: 200));
+  logger.trace('message 2');
+  logger.trace('message 3');
+
+  Progress progress = logger.progress('doing some work');
+  await new Future.delayed(new Duration(seconds: 2));
+  progress.finish(showTiming: true);
+
+  logger.stdout('All ${logger.ansi.emphasized('done')}.');
+  logger.flush();
+}
+```
+
 ## Features and bugs
 
 Please file feature requests and bugs at the [issue tracker][tracker].