Scroll to navigation

MU LABELS(1) General Commands Manual MU LABELS(1)

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.

A label is a string associated with a message.

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 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

Important: unlike other message metadata stored by mu, labels cannot be restored by merely re-indexing messages. Hence, to avoid loosing label information, you must export it before re-indexing, and import afterwards.

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.

--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.

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.

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.

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

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.

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.

—
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 UTF8-encoded text. 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.

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 

path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
labels:foo,bar,cuux

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 that if there are duplicate messages (messages with the same message-id), the tags are applied to all of them.

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.

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>

COPYRIGHT

This manpage is part of mu 1.12.13.

Copyright © 2008-2025 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

mu-query(1), mu-find(1),