From 656aa41ada8f6241e285c10e4682b10d295e8d73 Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Mon, 8 Sep 2025 21:45:39 +0300
Subject: [PATCH] rename 'mu label' -> 'mu labels'

Update names, docs etc.
---
 NEWS.org                                 |   7 +-
 man/meson.build                          |   2 +-
 man/mu-easy.7.org                        |   6 +-
 man/mu-init.1.org                        |   4 +-
 man/{mu-label.1.org => mu-labels.1.org}  |  59 +++++++-----
 mu/meson.build                           |   2 +-
 mu/{mu-cmd-label.cc => mu-cmd-labels.cc} | 114 ++++++++++++-----------
 mu/mu-cmd.cc                             |   8 +-
 mu/mu-cmd.hh                             |   4 +-
 mu/mu-options.cc                         |  73 +++++++--------
 mu/mu-options.hh                         |  17 ++--
 mu/tests/meson.build                     |   6 +-
 mu4e/mu4e.texi                           |   2 +-
 13 files changed, 155 insertions(+), 149 deletions(-)
 rename man/{mu-label.1.org => mu-labels.1.org} (69%)
 rename mu/{mu-cmd-label.cc => mu-cmd-labels.cc} (79%)

diff --git a/NEWS.org b/NEWS.org
index 668412d8..fe8c0810 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -127,9 +127,6 @@
       to it as a personal address. ~--my-address~ is still supported as an alias,
       for backward compatibility.
 
-    - 1.12.13: new (sub)command "labels", for associating searchable labels with
-      messages. See `man mu-label` for details.
-
     - 1.12.13: if available, *mu* now uses the system versions of ~CLI11~ and ~fmt~
       instead of the "vendored" ones. This can be overridden by passing the
       ~-Duse-embedded-cli11=true~ and ~-Duse-embedded-fmt=true~ to Meson.
@@ -138,6 +135,10 @@
       triggered when running the tests. This speed up the build when not
       testing
 
+    - 1.12.13: new (sub)command ~labels~, for associating searchable labels with
+      messages. Labels are similar to /tags/, but better integrated with *mu* (and
+      *mu4e*). See =man mu-labels= for details.
+
 *** mu4e
 
 **** message composer
diff --git a/man/meson.build b/man/meson.build
index 1034655c..5e35e1d8 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -55,7 +55,7 @@ man_orgs = [
   'mu-index.1.org',
   'mu-info.1.org',
   'mu-init.1.org',
-  'mu-label.1.org',
+  'mu-labels.1.org',
   'mu-mkdir.1.org',
   'mu-move.1.org',
   'mu-query.7.org',
diff --git a/man/mu-easy.7.org b/man/mu-easy.7.org
index aafeff47..430f303b 100644
--- a/man/mu-easy.7.org
+++ b/man/mu-easy.7.org
@@ -305,7 +305,7 @@ fields, since labels are not intrinsic parts of messages, so removing your
 message database, and then re-indexing won't bring back your labels.
 
 For that reason, you can export labels to a file and later import them again
-(see {{{man-link(mu-label,1)}}})
+(see {{{man-link(mu-labels,1)}}})
 
 Some examples:
 
@@ -329,7 +329,7 @@ There's also *mu label clear* to remove all labels from matching messages; and t
 the mutating *label* subcommands (*update*, *clear*, *import*) accept a *--dry-run* option
 for just printing what they /would/ change, without actually changing anything.
 
-{{{man-link(mu-label,1)}}} has all the details.
+{{{man-link(mu-labels,1)}}} has all the details.
 
 #+include: "prefooter.inc" :minlevel 1
 
@@ -343,4 +343,4 @@ for just printing what they /would/ change, without actually changing anything.
 {{{man-link(mu-mkdir,1)}}},
 {{{man-link(mu-view,1)}}},
 {{{man-link(mu-extract,1)}}}
-{{{man-link(mu-label,1)}}}
+{{{man-link(mu-labels,1)}}}
diff --git a/man/mu-init.1.org b/man/mu-init.1.org
index a451eeaa..945964ab 100644
--- a/man/mu-init.1.org
+++ b/man/mu-init.1.org
@@ -110,7 +110,7 @@ You can restore those labels _after_ re-indexing, e.g.,
 $ mu label import /home/user/.cache/mu/mu-export-2025-08-16-13:43:27.txt
 #+end_example
 
-Please see {{{man-link(mu-label,1)}}} for further details.
+Please see {{{man-link(mu-labels,1)}}} for further details.
 
 * EXAMPLE
 #+begin_example
@@ -123,6 +123,6 @@ $ mu init --maildir=~/Maildir --my-address=alice@example.com --my-address=bob@ex
 
 {{{man-link(mu-index,1)}}},
 {{{man-link(mu-find,1)}}},
-{{{man-link(mu-label,1)}}},
+{{{man-link(mu-labels,1)}}},
 {{{man-link(mu-cfind,1)}}},
 {{{man-link(pcre,3)}}}
diff --git a/man/mu-label.1.org b/man/mu-labels.1.org
similarity index 69%
rename from man/mu-label.1.org
rename to man/mu-labels.1.org
index 0bd9aeb4..88ed0f29 100644
--- a/man/mu-label.1.org
+++ b/man/mu-labels.1.org
@@ -1,34 +1,37 @@
-#+TITLE: MU LABEL
+#+TITLE: MU LABELS
 #+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 #+include: macros.inc
 
 * NAME
 
-mu-label - attach labels to messages. Export labels to file, and import them.
+mu-labels - attach labels to messages. Export labels to file, and import them.
 
 * SYNOPSIS
 
-*mu* [​_COMMON-OPTIONS_​] *label* update [​UPDATE-OPTIONS​] "<query>" --labels [{+,-}<label>]...
+*mu* [​_COMMON-OPTIONS_​] labels update [​UPDATE-OPTIONS​] "<query>" --labels [{+,-}<label>]...
 
-*mu* [​_COMMON-OPTIONS_​] *label* list [LIST-OPTIONS]
+*mu* [​_COMMON-OPTIONS_​] labels list
 
-mu [​_COMMON-OPTIONS_​] *label* clear [CLEAR-OPTIONS] "<query>"
+*mu* [​_COMMON-OPTIONS_​] labels list-restore
 
-mu [​_COMMON-OPTIONS_​] *label* export [<file>]
+*mu* [​_COMMON-OPTIONS_​] labels clear [CLEAR-OPTIONS] "<query>"
 
-mu [​_COMMON-OPTIONS_​] *label* import <file>
+*mu* [​_COMMON-OPTIONS_​] labels export [<file>]
+
+*mu* [​_COMMON-OPTIONS_​] labels import <file>
 
 * DESCRIPTION
 
-*mu label* is the sub-command for adding and removing and listing message labels.
+*mu labels* is the sub-command for adding and removing and listing message labels.
 
 A label is a string associated with a message.
 
-*mu label* has five sub-commands (i.e., 'sub-sub-commands'):
+*mu labels* has five sub-commands (i.e., 'sub-sub-commands'):
 
 - *update* for changing the labels for the messages matching some query
 - *clear* for clearing all labels from messages matching some query
-- *list* to list all labels that are in use in the store
+- *list* to list all labels that are used in the store
+- *list-restore* to restore the list of labels from the store
 - *export* to write the label information to a file
 - *import* the read label information from a file
 
@@ -38,7 +41,7 @@ must *export* it before re-indexing, and *import* afterwards.
 
 * UPDATE OPTIONS
 
-The *update* coxmmand changes the labels for messages that match some query. The
+The *update* command changes the labels for messages that match some query. The
 query must be recognized as a single parameter; hence, it must be quoted when
 using from a shell.
 
@@ -66,20 +69,21 @@ when using a shell.
 
   only print what /would/ change, but do not change anything
 
-#+include: "muhome.inc" :minlevel 2
+  #+include: "muhome.inc" :minlevel 2
 
 * LIST OPTIONS
 
 The *list* command lists all the labels that are currently in use in the store.
-This is the same information used for auto-completion in *mu4e*.
+This is the information is used for auto-completion in *mu4e*.
 
 With the (global, directly after *mu) *--verbose* option, this also includes the
 counts.
 
-** --restore
+* LIST-RESTORE OPTIONS
 
-  attempt to restore the list from the labels in the store.
-  It is possible that the list to get outdated, *--restore* fixes this.
+It is possible that the list of labels (as per the *list* sub-command) gets
+outdated for various reasons. With *list-restore*, this list get refreshed with
+the actual labels as seen in the store.
 
 * EXPORT OPTIONS
 
@@ -125,14 +129,19 @@ ones are: ~holiday plan~ and ~+fancy$/dinner~.
 
 * EXPORT FORMAT
 
-The formats for import/export are UTF-8 encoded text. The first line starts with
+The formats for import/export are UTF8-encoded text. The first line starts with
 ~;;~ and some internal data. Empty lines are ignored.
 
-Each entry represents the tags for a message. It consists of three lines. The
-first starts with ~path:~ followed by the file-system path to the message. The
-second line starts with ~message-id:~ followed by the message-id for the message.
-Finally, the third line starts with ~tag:~ followed by space-separated tags for
-the message
+Each entry represents the labels for a message. Messages without labels are not
+included.
+
+An entry consists of three lines:
+1. The first line starts with ~path:~ followed by the file-system path to the
+   message.
+2. The second line starts with ~message-id:~ followed by the message-id for the
+   message.
+3. Finally, the third line starts with ~labels:~ followed by the space-separated
+   labels for the message
 
 #+begin_example
 path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
@@ -140,7 +149,7 @@ message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
 labels:foo,bar,cuux
 #+end_example
 
-Note, the ~message-id:~ is only used if the message cannot be found using ~path:~.
+The ~message-id:~ is only used if the message cannot be found using ~path:~.
 
 This adds some fault-tolerance for the case where the precise file-system
 positions have changed since the labels were exported. The upshot of that is
@@ -157,12 +166,12 @@ it is recognized as a single parameter.
 Remove the label "planet" and add the label "dwarf-planet" to all messages that
 have "pluto" in their subject:
 #+begin_export
-$ mu label update "subject:pluto" --labels -planet,+dwarf-planet
+$ mu labels update "subject:pluto" --labels -planet,+dwarf-planet
 #+end_export
 
 Clear all labels from messages with the label "boring":
 #+begin_export
-$ mu label clear "label:boring"
+$ mu labels clear "label:boring"
 #+end_export
 
 #+include: "prefooter.inc" :minlevel 1
diff --git a/mu/meson.build b/mu/meson.build
index f785796f..84941bea 100644
--- a/mu/meson.build
+++ b/mu/meson.build
@@ -25,7 +25,7 @@ mu = executable(
   'mu-cmd-info.cc',
   'mu-cmd-init.cc',
   'mu-cmd-index.cc',
-  'mu-cmd-label.cc',
+  'mu-cmd-labels.cc',
   'mu-cmd-mkdir.cc',
   'mu-cmd-move.cc',
   'mu-cmd-remove.cc',
diff --git a/mu/mu-cmd-label.cc b/mu/mu-cmd-labels.cc
similarity index 79%
rename from mu/mu-cmd-label.cc
rename to mu/mu-cmd-labels.cc
index 72c9798c..9f373e31 100644
--- a/mu/mu-cmd-label.cc
+++ b/mu/mu-cmd-labels.cc
@@ -37,7 +37,7 @@ label_update(Mu::Store& store, const Options& opts)
 	// First get our list of parsed delta-label, and ensure they
 	// are valid.
 	DeltaLabelVec deltas{};
-	for (auto&& delta_label : opts.label.delta_labels) {
+	for (auto&& delta_label : opts.labels.delta_labels) {
 	  if (const auto res = parse_delta_label(delta_label); !res)
 		  return Err(Error{Error::Code::InvalidArgument,
 				   "invalid delta-label '{}': {}", delta_label,
@@ -46,12 +46,12 @@ label_update(Mu::Store& store, const Options& opts)
 		  deltas.emplace_back(std::move(*res));
 	}
 
-	if (!opts.label.query)
+	if (!opts.labels.query)
 		return Err(Error{Error::Code::Query,
 				 "missing query"});
 
 	// now run the query and apply the deltas to each.
-	const auto query{*opts.label.query};
+	const auto query{*opts.labels.query};
 	auto results{store.run_query(query)};
 	if (!results)
 		return Err(Error{Error::Code::Query,
@@ -59,23 +59,23 @@ label_update(Mu::Store& store, const Options& opts)
 
 	// seems we got some results... let's apply to each
 	size_t n{};
-	const auto labelstr{join(opts.label.delta_labels, " ")};
+	const auto labelstr{join(opts.labels.delta_labels, " ")};
 	for (auto&& result : *results) {
 		if (auto &&msg{result.message()}; msg) {
 
-			if (opts.label.dry_run || opts.verbose)
+			if (opts.labels.dry_run || opts.verbose)
 				mu_println("labels: apply {} to {}", labelstr, msg->path());
 
-			if (!opts.label.dry_run) {
+			if (!opts.labels.dry_run) {
 				store.update_labels(*msg, deltas);
 			}
 			++n;
 		}
 	}
 
-	if (opts.verbose || opts.label.dry_run)
+	if (opts.verbose || opts.labels.dry_run)
 		mu_println("labels: {}updated {} message(s)",
-			   opts.label.dry_run ? "would have " : "", n);
+			   opts.labels.dry_run ? "would have " : "", n);
 
 	return Ok();
 }
@@ -83,11 +83,11 @@ label_update(Mu::Store& store, const Options& opts)
 static Result<void>
 label_clear(Mu::Store& store, const Options& opts)
 {
-	if (!opts.label.query)
+	if (!opts.labels.query)
 		return Err(Error{Error::Code::Query,
 				 "missing query"});
 
-	const auto query{*opts.label.query};
+	const auto query{*opts.labels.query};
 	auto results{store.run_query(query)};
 	if (!results)
 		return Err(Error{Error::Code::Query,
@@ -97,19 +97,19 @@ label_clear(Mu::Store& store, const Options& opts)
 	for (auto&& result : *results) {
 		if (auto &&msg{result.message()}; msg) {
 
-			if (opts.label.dry_run || opts.verbose)
+			if (opts.labels.dry_run || opts.verbose)
 				mu_println("labels: clear all from {}", msg->path());
 
-			if (!opts.label.dry_run) {
+			if (!opts.labels.dry_run) {
 				store.clear_labels(*msg);
 			}
 			++n;
 		}
 	}
 
-	if (opts.verbose || opts.label.dry_run)
+	if (opts.verbose || opts.labels.dry_run)
 		mu_println("labels: {}cleared {} message(s)",
-			   opts.label.dry_run ? "would have " : "", n);
+			   opts.labels.dry_run ? "would have " : "", n);
 
 	return Ok();
 }
@@ -117,14 +117,6 @@ label_clear(Mu::Store& store, const Options& opts)
 static Result<void>
 label_list(Mu::Store& store, const Options& opts)
 {
-	if (opts.label.restore) {
-		if (!opts.quiet)
-			mu_println("labels: restoring list from store...");
-		if (const auto res = store.restore_label_map(); !res) {
-			return res;
-		}
-	}
-
 	for (const auto& [label, n]: store.label_map())
 		if (opts.verbose)
 			mu_println("{}: {}", label, n);
@@ -134,10 +126,24 @@ label_list(Mu::Store& store, const Options& opts)
 	return Ok();
 }
 
+
+
+static Result<void>
+label_restore_list(Mu::Store& store, const Options& opts)
+{
+	if (!opts.quiet)
+		mu_println("labels: restoring list from store...");
+	if (const auto res = store.restore_label_map(); !res || opts.quiet)
+		return res;
+
+	return label_list(store, opts);
+}
+
+
 static Result<void>
 label_export(const Mu::Store& store, const Options& opts)
 {
-	const auto res = export_labels(store, "", opts.label.file);
+	const auto res = export_labels(store, "", opts.labels.file);
 	if (!res)
 		return Err(res.error());
 
@@ -151,27 +157,29 @@ static Result<void>
 label_import(Mu::Store& store, const Options& opts)
 {
 	// sanity check, should be caught during arg parsing
-	if (!opts.label.file)
+	if (!opts.labels.file)
 		return Err(Error{Error::Code::InvalidArgument,
 				"missing input file"});
 
-	return Mu::import_labels(store, *opts.label.file,
-				     opts.label.dry_run, opts.quiet, opts.verbose);
+	return Mu::import_labels(store, *opts.labels.file,
+				     opts.labels.dry_run, opts.quiet, opts.verbose);
 }
 
 Result<void>
-Mu::mu_cmd_label(Mu::Store &store, const Options &opts)
+Mu::mu_cmd_labels(Mu::Store &store, const Options &opts)
 {
-	switch (opts.label.sub) {
-	case Options::Label::Sub::List:
+	switch (opts.labels.sub) {
+	case Options::Labels::Sub::List:
 		return label_list(store, opts);
-	case Options::Label::Sub::Update:
+	case Options::Labels::Sub::RestoreList:
+		return label_restore_list(store, opts);
+	case Options::Labels::Sub::Update:
 		return label_update(store, opts);
-	case Options::Label::Sub::Clear:
+	case Options::Labels::Sub::Clear:
 		return label_clear(store, opts);
-	case Options::Label::Sub::Export:
+	case Options::Labels::Sub::Export:
 		return label_export(store, opts);
-	case Options::Label::Sub::Import:
+	case Options::Labels::Sub::Import:
 		return label_import(store, opts);
 
 	default:
@@ -193,11 +201,11 @@ Mu::mu_cmd_label(Mu::Store &store, const Options &opts)
 static std::string test_mu_home;
 
 static void
-test_mu_label_update()
+test_mu_labels_update()
 {
 	{
 		const auto res = run_command({MU_PROGRAM,
-			"label", "update", "subject:abc",
+			"labels", "update", "subject:abc",
 			"--labels", "+foo,-bar",
 			"--muhome", test_mu_home});
 		assert_valid_result(res);
@@ -223,7 +231,7 @@ test_mu_label_update()
 
 	{
 		const auto res = run_command({MU_PROGRAM,
-			"label", "update",
+			"labels", "update",
 			"subject:abc",
 			"--labels", "-foo,+bar",
 			"--muhome", test_mu_home});
@@ -250,11 +258,11 @@ test_mu_label_update()
 }
 
 static void
-test_mu_label_clear()
+test_mu_labels_clear()
 {
 	{
 		const auto res = run_command({MU_PROGRAM,
-			"label", "update", "subject:abc",
+			"labels", "update", "subject:abc",
 			"--labels", "+foo",
 			"--muhome", test_mu_home});
 		assert_valid_result(res);
@@ -271,7 +279,7 @@ test_mu_label_clear()
 	}
 	{
 		const auto res = run_command({MU_PROGRAM,
-			"label", "clear", "subject:abc",
+			"labels", "clear", "subject:abc",
 			"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -289,11 +297,11 @@ test_mu_label_clear()
 
 
 static void
-test_mu_label_list()
+test_mu_labels_list()
 {
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "update", "subject:abc",
+				"labels", "update", "subject:abc",
 				"--labels", "+foo,-bar,+cuux,+fnorb",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
@@ -302,7 +310,7 @@ test_mu_label_list()
 
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "update", "subject:abc",
+				"labels", "update", "subject:abc",
 				"--labels", "-cuux",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
@@ -312,7 +320,7 @@ test_mu_label_list()
 
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "list",
+				"labels", "list",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -322,7 +330,7 @@ test_mu_label_list()
 }
 
 static void
-test_mu_label_export_import()
+test_mu_labels_export_import()
 {
 	TempDir temp_dir{};
 	const auto exportfile{join_paths(temp_dir.path(), "export.txt")};
@@ -330,7 +338,7 @@ test_mu_label_export_import()
 	// ensure  there are some labels (from previous test)
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "list",
+				"labels", "list",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -342,7 +350,7 @@ test_mu_label_export_import()
 	// fnorb,foo
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "export", exportfile,
+				"labels", "export", exportfile,
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -362,7 +370,7 @@ test_mu_label_export_import()
 	// ensure the labels are gone.
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "list",
+				"labels", "list",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -372,7 +380,7 @@ test_mu_label_export_import()
 	// import the labels
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "import", exportfile,
+				"labels", "import", exportfile,
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -381,7 +389,7 @@ test_mu_label_export_import()
 	// ensure the label are back
 	{
 		const auto res = run_command({MU_PROGRAM,
-				"label", "list",
+				"labels", "list",
 				"--muhome", test_mu_home});
 		assert_valid_result(res);
 		g_assert_cmpuint(res->exit_code,==,0);
@@ -410,10 +418,10 @@ main(int argc, char* argv[])
 		assert_valid_result(res2);
 	}
 
-	g_test_add_func("/cmd/label/update", test_mu_label_update);
-	g_test_add_func("/cmd/label/clear",  test_mu_label_clear);
-	g_test_add_func("/cmd/label/list",   test_mu_label_list);
-	g_test_add_func("/cmd/label/export-import",   test_mu_label_export_import);
+	g_test_add_func("/cmd/labels/update", test_mu_labels_update);
+	g_test_add_func("/cmd/labels/clear", test_mu_labels_clear);
+	g_test_add_func("/cmd/labels/list", test_mu_labels_list);
+	g_test_add_func("/cmd/labels/export-import", test_mu_labels_export_import);
 
 
 	return g_test_run();
diff --git a/mu/mu-cmd.cc b/mu/mu-cmd.cc
index f358311b..8efe3472 100644
--- a/mu/mu-cmd.cc
+++ b/mu/mu-cmd.cc
@@ -177,11 +177,11 @@ Mu::mu_cmd_execute(const Options& opts) try {
 	/*
 	 *  read-only _or_ writable store
 	 */
-	case Options::SubCommand::Label:
-		if (opts.label.read_only)
-			return with_readonly_store2(mu_cmd_label, opts);
+	case Options::SubCommand::Labels:
+		if (opts.labels.read_only)
+			return with_readonly_store2(mu_cmd_labels, opts);
 		else
-			return with_writable_store(mu_cmd_label, opts);
+			return with_writable_store(mu_cmd_labels, opts);
 	/*
 	 * commands instantiate store themselves
 	 */
diff --git a/mu/mu-cmd.hh b/mu/mu-cmd.hh
index 35fcfcca..e5ddb624 100644
--- a/mu/mu-cmd.hh
+++ b/mu/mu-cmd.hh
@@ -117,14 +117,14 @@ Result<void> mu_cmd_info(const Mu::Store& store, const Options& opts);
 Result<void> mu_cmd_init(const Options& opts);
 
 /**
- * execute the 'label' command
+ * execute the 'labels' sub-command
  *
  * @param store message store object.
  * @param opts configuration options
  *
  * @return Ok() or some error
  */
-Result<void> mu_cmd_label(Store& store, const Options& opts);
+Result<void> mu_cmd_labels(Store& store, const Options& opts);
 
 /**
  * execute the 'mkdir' command
diff --git a/mu/mu-options.cc b/mu/mu-options.cc
index 3d9f0da6..58e13858 100644
--- a/mu/mu-options.cc
+++ b/mu/mu-options.cc
@@ -33,7 +33,6 @@
  *
  */
 
-
 #include <config.h>
 #include <stdexcept>
 #include <array>
@@ -68,7 +67,6 @@ using namespace Mu;
 template<typename T1, typename T2, std::size_t N>
       using AssocPairs = std::array<std::pair<T1, T2>, N>;
 
-
 /**
   * Get the first value of the pair where the second element is @param s.
   *
@@ -105,7 +103,6 @@ to_second(const P& p, typename P::value_type::first_type f)
 	return Nothing;
 }
 
-
 /**
  * Options-specific array-bases type that maps some enum to a <name, description> pair
  */
@@ -170,7 +167,6 @@ options_help(const IE& ie, typename IE::value_type::first_type default_opt)
 	return s;
 }
 
-
 /**
  * Get map from string->type
  */
@@ -275,7 +271,6 @@ sub_cfind(CLI::App& sub, Options& opts)
 }
 
 
-
 static void
 sub_extract(CLI::App& sub, Options& opts)
 {
@@ -328,7 +323,6 @@ sub_fields(CLI::App& sub, Options& opts)
 	// nothing to do.
 }
 
-
 static void
 sub_find(CLI::App& sub, Options& opts)
 {
@@ -447,7 +441,6 @@ sub_index(CLI::App& sub, Options& opts)
 		     "Perform a complete reindexing");
 }
 
-
 static void
 sub_info(CLI::App& sub, Options& opts)
 {
@@ -501,48 +494,51 @@ sub_init(CLI::App& sub, Options& opts)
 }
 
 static void
-sub_label(CLI::App& sub, Options& opts)
+sub_labels(CLI::App& sub, Options& opts)
 {
-	sub.require_subcommand(1);
+	sub.require_subcommand(0);
 
 	// update
 	auto update{sub.add_subcommand("update", "update labels")};
-	update->add_option("--labels", opts.label.delta_labels,
+	update->add_option("--labels", opts.labels.delta_labels,
 		       "One or more comma-separated +label,-label")
 		->delimiter(',')
 		->type_name("<delta-label>")
 		->required();
-	update->add_flag("-n,--dry-run", opts.label.dry_run,
+	update->add_flag("-n,--dry-run", opts.labels.dry_run,
 		     "Output what would change without changing anything");
-	update->add_option("query", opts.label.query, "Query for messages to update")
+	update->add_option("query", opts.labels.query, "Query for messages to update")
 		->required();
 	add_muhome_option(*update, opts);
 
 	// clear
 	auto clear = sub.add_subcommand("clear", "clear all labels from matched messages");
-	clear ->add_option("query", opts.label.query, "Query for messages to clear of labels")
+	clear ->add_option("query", opts.labels.query, "Query for messages to clear of labels")
 		->required();
-	clear->add_flag("-n,--dry-run", opts.label.dry_run,
+	clear->add_flag("-n,--dry-run", opts.labels.dry_run,
 		     "Output what would change without changing anything");
 	add_muhome_option(*clear, opts);
 
 	// list
 	[[maybe_unused]] auto list = sub.add_subcommand("list", "list labels in the store");
-	list->add_flag("--restore", opts.label.restore,
-			 "Restore the label-list from the labels in store");
 	add_muhome_option(*list, opts);
 
+	// restore-list
+	[[maybe_unused]] auto restore_list = sub.add_subcommand(
+		"restore-list", "restore the labels cache");
+	add_muhome_option(*restore_list, opts);
+
 	// export
 	[[maybe_unused]] auto exportsub = sub.add_subcommand("export", "export labels to a file");
 	add_muhome_option(*exportsub, opts);
-	exportsub->add_option("output", opts.label.file, "File to export labels to")
+	exportsub->add_option("output", opts.labels.file, "File to export labels to")
 		->type_name("<file>");
 
 	// import
 	auto importsub = sub.add_subcommand("import", "import labels from a file");
-	importsub->add_flag("-n,--dry-run", opts.label.dry_run,
+	importsub->add_flag("-n,--dry-run", opts.labels.dry_run,
 			    "Output what would change without changing anything");
-	importsub->add_option("input", opts.label.file, "File with labels to import")
+	importsub->add_option("input", opts.labels.file, "File with labels to import")
 		->required()
 		->type_name("<file>");
 	add_muhome_option(*importsub, opts);
@@ -555,25 +551,27 @@ sub_label(CLI::App& sub, Options& opts)
 
 	sub.final_callback([&](){
 		if (sub.got_subcommand("list")) {
-			opts.label.sub = Options::Label::Sub::List;
-			opts.label.read_only = opts.label.restore ? false : true;
+			opts.labels.sub = Options::Labels::Sub::List;
+			opts.labels.read_only = true;
+		} else if (sub.got_subcommand("restore-list")) {
+			opts.labels.sub = Options::Labels::Sub::RestoreList;
+			opts.labels.read_only  = false;/*opts.labels.dry_run*/
 		} else if (sub.got_subcommand("clear")) {
-			opts.label.sub = Options::Label::Sub::Clear;
-			opts.label.read_only = opts.label.dry_run;
+			opts.labels.sub = Options::Labels::Sub::Clear;
+			opts.labels.read_only = opts.labels.dry_run;
 		} else if (sub.got_subcommand("update")){
-			opts.label.sub = Options::Label::Sub::Update;
-			opts.label.read_only = opts.label.dry_run;
+			opts.labels.sub = Options::Labels::Sub::Update;
+			opts.labels.read_only = opts.labels.dry_run;
 		} else if (sub.got_subcommand("export")){
-			opts.label.sub = Options::Label::Sub::Export;
-			opts.label.read_only = true;
+			opts.labels.sub = Options::Labels::Sub::Export;
+			opts.labels.read_only = true;
 		} else if (sub.got_subcommand("import")){
-			opts.label.sub = Options::Label::Sub::Import;
-			opts.label.read_only = opts.label.dry_run;
+			opts.labels.sub = Options::Labels::Sub::Import;
+			opts.labels.read_only = opts.labels.dry_run;
 		}
 	});
 }
 
-
 static void
 sub_mkdir(CLI::App& sub, Options& opts)
 {
@@ -586,7 +584,6 @@ sub_mkdir(CLI::App& sub, Options& opts)
 		->required();
 }
 
-
 static void
 sub_move(CLI::App& sub, Options& opts)
 {
@@ -609,7 +606,6 @@ sub_move(CLI::App& sub, Options& opts)
 		->type_name("<maildir>");
 }
 
-
 static void
 sub_remove(CLI::App& sub, Options& opts)
 {
@@ -719,7 +715,6 @@ sub_view(CLI::App& sub, Options& opts)
 		->type_name("<message-path>");
 }
 
-
 using	SubCommand = Options::SubCommand;
 using   Category   = Options::Category;
 
@@ -771,9 +766,9 @@ AssocPairs<SubCommand, CommandInfo, Options::SubCommandNum> SubCommandInfos= {{
 		  {Category::NeedsWritableStore,
 		  "init", "Initialize the mu database", sub_init }
 		},
-		{ SubCommand::Label,
+		{ SubCommand::Labels,
 		  {Category::None, // note Store handled on sub-subcommmands
-		  "label", "Add/remove labels form messages", sub_label }
+		  "labels", "Manage message labels", sub_labels }
 		},
 		{ SubCommand::Mkdir,
 		  {Category::None,
@@ -811,7 +806,6 @@ AssocPairs<SubCommand, CommandInfo, Options::SubCommandNum> SubCommandInfos= {{
 		},
 	}};
 
-
 static ScriptInfos
 add_scripts(CLI::App& app, Options& opts)
 {
@@ -832,7 +826,6 @@ add_scripts(CLI::App& app, Options& opts)
 #endif /*BUILD_GUILE*/
 }
 
-
 static Result<Options>
 show_manpage(Options& opts, const std::string& name)
 {
@@ -851,7 +844,6 @@ show_manpage(Options& opts, const std::string& name)
 	return Ok(std::move(opts));
 }
 
-
 static Result<Options>
 cmd_help(const CLI::App& app, Options& opts)
 {
@@ -905,7 +897,7 @@ Result<Options>
 Options::make(int argc, char *argv[])
 {
 	Options opts{};
-	CLI::App app{"mu mail indexer/searcher", "mu"};
+	CLI::App app{"mu mail indexer/searcher " PACKAGE_VERSION, "mu"};
 
 	app.description(R"(mu mail indexer/searcher
 Copyright (C) 2008-2025 Dirk-Jan C. Binnema
@@ -915,7 +907,7 @@ This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 )");
 	app.set_version_flag("-V,--version", PACKAGE_VERSION);
-	app.set_help_flag("-h,--help", "Show help informmation");
+	app.set_help_flag("-h,--help", "Show help information");
 	app.set_help_all_flag("--help-all");
 	app.require_subcommand(0, 1);
 
@@ -1031,7 +1023,6 @@ validate_subcommand_ids()
 #define static_assert g_assert_true
 #endif /*BUILD_TESTS*/
 
-
 [[maybe_unused]]
 static void
 test_ids()
diff --git a/mu/mu-options.hh b/mu/mu-options.hh
index 66902ff0..9bef3db2 100644
--- a/mu/mu-options.hh
+++ b/mu/mu-options.hh
@@ -62,7 +62,7 @@ struct Options {
 	static bool default_no_color();
 
 	enum struct SubCommand {
-		Add, Cfind, Extract, Fields, Find, Help, Index,Info, Init, Label, Mkdir,
+		Add, Cfind, Extract, Fields, Find, Help, Index,Info, Init, Labels, Mkdir,
 		Move, Remove, Scm, Script, Server, Verify, View,
 		// <private>
 		__count__
@@ -78,7 +78,7 @@ struct Options {
 			SubCommand::Index,
 			SubCommand::Info,
 			SubCommand::Init,
-			SubCommand::Label,
+			SubCommand::Labels,
 			SubCommand::Mkdir,
 			SubCommand::Move,
 			SubCommand::Remove,
@@ -202,29 +202,26 @@ struct Options {
 	} init;
 
 	/*
-	 * Label
+	 * Labels
 	 */
-	struct Label {
+	struct Labels {
 		OptString query;                         /**< Query for the messages to label */
 		bool dry_run{};				 /**< Merely print the messages that would be
 							  * labeled without doing so */
 		StringVec delta_labels;                  /**< labels to add (+) or remove (-) */
 		bool read_only{};                        /**< do not require writable store */
-
-		bool restore{};                         /**< restore the labels list */
-
 		OptString file;                           /** file for import/export */
 
 		enum struct Sub { // sub-subcommands
 			Update, //  add/remove labels
 			Clear,  // clear all labels
-			List,   // list all labels in the store
+			List,   // list all labels in the store (from cache)
+			RestoreList, // restore the labels cache
 			Export, // export labels
 			Import, // import labels
 		};
 		Sub sub;
-	} label;
-
+	} labels;
 
 	/*
 	 * Mkdir
diff --git a/mu/tests/meson.build b/mu/tests/meson.build
index ed56405d..fff02481 100644
--- a/mu/tests/meson.build
+++ b/mu/tests/meson.build
@@ -66,9 +66,9 @@ test('test-cmd-init',
                 build_by_default: false,
                 cpp_args: ['-DBUILD_TESTS'],
                 dependencies: [glib_dep, lib_mu_dep]))
-test('test-cmd-label',
-     executable('test-cmd-label',
-                '../mu-cmd-label.cc',
+test('test-cmd-labels',
+     executable('test-cmd-labels',
+                '../mu-cmd-labels.cc',
                 install: false,
                 build_by_default: false,
                 cpp_args: ['-DBUILD_TESTS'],
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index 10821043..b65e1802 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -2550,7 +2550,7 @@ You can search for labels using the @t{label:} field. For instance,
 are not changed). This means that you would @emph{loose} this information when
 you remove the database and recreate it, @emph{unless} you @emph{export} the
 labels before removin the database and re-@emph{import} them after re-creating
-and re-indexing it; see the @t{mu-label} man-page for further details.
+and re-indexing it; see the @command{mu-labels} man-page for further details.
 
 @subsection Doing @emph{something}