MU-LABELS(1)

📦
version 1.14.2 · 5 versions
, in ubuntu stonking

💖 MU-LABELS(1) — the manual, but make it cute 💖

okay bestie, sit down, hydrate, and let's talk about mu-labels, aka the mu sub-command that says "this message deserves a little name tag" 🎀. This lil guy lives in the General Commands Manual for the mu mail indexer, and it's literally the labels plug-in you didn't know you needed.

✨ NAME ✨

mu-labels — attach labels to messages. Export labels to file, and import them.

🌸 SYNOPSIS 🌸

mu [COMMON-OPTIONS] labels update [UPDATE-OPTIONS] "<query>" --labels [{+,-}<label>]...

mu [COMMON-OPTIONS] labels list

mu [COMMON-OPTIONS] labels list-restore

mu [COMMON-OPTIONS] labels clear [CLEAR-OPTIONS] "<query>"

mu [COMMON-OPTIONS] labels export [<file>]

mu [COMMON-OPTIONS] labels import <file>

💅 DESCRIPTION 💅

mu labels is the sub-command for adding and removing and listing message labels. no cap.

A label is a string associated with a message. that's it. that's the whole vibe. 🦋

mu labels has six sub-commands (i.e., 'sub-sub-commands'). say that three times fast:

  • 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 used in the store
  • list-restore to restore the list of labels from the database (store)
  • export to write the label information to a file
  • import the read label information from a file
Important, bestie, listen to me: unlike other message metadata stored by mu, labels cannot be restored by merely re-indexing messages, since the information is not part of the message files. Hence, to avoid loosing label information, you must export it before re-indexing, and import afterwards. 🚨 Do NOT skip this step, I am begging. 😭

🔥 UPDATE OPTIONS 🔥

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.

  • --labels — a comma-separated list of labels, each prefixed with either + to add that label, or - to remove it. See VALID LABELS.
mu4e users: note the difference, in mu4e the label expressions are space-separated, here they are comma-separated. ⚠️ yes fr fr, read it twice. it's giving "easy to mess up".
  • --dry-run — only print what would change, but do not change anything. window shopping only, no purchases. 🛍️
  • --muhome — Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Earlier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu.

The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 👑

🧚 CLEAR OPTIONS 🧚

The clear command removes all labels from messages that match some query. As with update, the query must be recognized as a single parameter, i.e., quote it when using a shell.

  • --dry-run — only print what would change, but do not change anything. 👀
  • --muhome — Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Earlier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu.

The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 💖

🌈 LIST OPTIONS 🌈

The list command lists all the labels that are currently in use in the store. This is the information is used for auto-completion in mu4e. ✨ autocomplete is iconic, honestly.

With the (global, directly after mu) --verbose option, this also includes the counts. 🔢

🫶 LIST-RESTORE OPTIONS 🫶

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. it's the glow-up/resync moment. 🦋

📦 EXPORT OPTIONS 📦

The export command takes the labels in the store and the messages they apply to, and writes this information to a file. You can import this file later, to restore the labels. The command takes a path to a file or a directory (ending in /) as its argument.

  • If a file is specified, mu writes the export to it.
  • If a directory is specified, mu writes to a file in that directory. The directory must already exist. (don't make it make the dir, it will not 🙈)
  • When neither is specified, mu writes to a file in the current directory.

See EXPORT FORMAT below for details about the format.

🌟 IMPORT OPTIONS 🌟

The import command is for restoring the labels from a file created through export earlier. The command takes a path to a file as its argument.

See EXPORT FORMAT below for details on the format.

  • --dry-run — only print what would change, but do not change anything. 🌙
  • --muhome — Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Earlier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu.

The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 🎀

👑 VALID LABELS 👑

mu does not wish to limit your creativity, but nevertheless puts a few restrictions on what is accepted as a label. it's not a hater, it just has boundaries. 💅

  • a valid label character is any character that is not a control-character, not a blank, nor anything matching the regular expression [^
  • a valid label consists of one or more valid label characters, the first of which must not be either + or -

Hence, some valid labels are: project-x, c@pybara, fn😃rb, while some invalid ones are: holiday plan and +fancy$/dinner.

🎀 EXPORT FORMAT 🎀

The formats for import/export are text encoded as UTF-8. The first line starts with ;; and some internal data. Empty lines are ignored.

Each entry represents the labels for a message. Messages without labels are not included. (if you have no labels, you're simply not in the group chat 💀)

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 a comma-separated list of labels for the message
path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
labels:foo,bar,cuux

💜 Import using message-id 💜

The message-id: line is only used if the message cannot be found using path:.

This helps for the case where the precise file-system are not precisely the same as those used when exporting. This happens, for instance, when changes were made to the message flags since the export. Or when trying to import on a different machine with different paths.

In any case, when using the message-id for importing, any duplicate messages (messages with the same message-id), all get the same labels. no favorites, everyone gets the same sticker. ⭐

💀 EXIT CODE 💀

This command returns 0 upon successful completion, or a non-zero exit code otherwise.

  • 0 — success 🎉
  • 2 — no matches found. Try a different query
  • 11 — database schema mismatch. You need to re-initialize mu, see mu-init(1)
  • 19 — failed to acquire lock. Some other program has exclusive access to the mu database
  • 99 — caught an exception

⭐ EXAMPLES ⭐

Some examples. For the query parameter, make sure to quote the query to ensure it is recognized as a single parameter. quoting is your bestie here, periodt.

Remove the label "planet" and add the label "dwarf-planet" to all messages that have "pluto" in their subject:

$ mu labels update "subject:pluto" --labels -planet,+dwarf-planet

Clear all labels from messages with the label "boring":

$ mu labels clear "label:boring"

🙈 REPORTING BUGS 🙈

Please report bugs at https://github.com/djcb/mu/issues.

🌸 AUTHOR 🌸

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

This manpage is part of mu 1.14.2.

Copyright © 2008-2026 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

🦋 SEE ALSO 🦋

okay that's the whole thing!! you're now officially fluent in mu-labels, go label your mail like the main character you are 👑 — that was MU LABELS(1), from the General Commands Manual, shipped with mu 1.14.2, and yes the copyright still says 2008-2026, we love a long-running icon. byeeeee 💖✨🎀

📦 where this page comes from