I'm just noticing that 'notmuch help ...' outputs to stderr, which
isn't terribly intuitive.  For example, the obvious invocation:

  notmuch help | less

...isn't terribly helpful.

I've attached a patch that lets usage() take a FILE * argument so that
you can output to stderr in response to usage errors, and stdout in
response to an explicit request.

-- 
Lars Kellogg-Stedman <lars@seas.harvard.edu>
Senior Technologist, Computing and Information Technology
Harvard University School of Engineering and Applied Sciences

diff --git a/notmuch.c b/notmuch.c
index c47e640..a35cb99 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -157,23 +157,23 @@ command_t commands[] = {
 };
 
 static void
-usage (void)
+usage (FILE *out)
 {
     command_t *command;
     unsigned int i;
 
-    fprintf (stderr, "Usage: notmuch <command> [args...]\n");
-    fprintf (stderr, "\n");
-    fprintf (stderr, "Where <command> and [args...] are as follows:\n");
-    fprintf (stderr, "\n");
+    fprintf (out, "Usage: notmuch <command> [args...]\n");
+    fprintf (out, "\n");
+    fprintf (out, "Where <command> and [args...] are as follows:\n");
+    fprintf (out, "\n");
 
     for (i = 0; i < ARRAY_SIZE (commands); i++) {
 	command = &commands[i];
 
-	fprintf (stderr, "\t%s\t%s\n\n", command->name, command->summary);
+	fprintf (out, "\t%s\t%s\n\n", command->name, command->summary);
     }
 
-    fprintf (stderr, "Use \"notmuch help <command>\" for more details on each command.\n\n");
+    fprintf (out, "Use \"notmuch help <command>\" for more details on each command.\n\n");
 }
 
 static int
@@ -183,8 +183,8 @@ notmuch_help_command (unused (void *ctx), int argc, char *argv[])
     unsigned int i;
 
     if (argc == 0) {
-	fprintf (stderr, "The notmuch mail system.\n\n");
-	usage ();
+	fprintf (stdout, "The notmuch mail system.\n\n");
+	usage (stdout);
 	return 0;
     }