Find the Right Dovecot Command with doveadm help

You know Dovecot can do the thing, but not which doveadm subcommand does it, and guessing on a live mail server is a bad plan. doveadm help lists the command groups and opens the manual page for one before you run anything. It takes about ten minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm which installation you are using
2. List the available command groups
3. Open the page for a command group
4. Read the global options without applying them
5. Move on to an operational command carefully

The examples match Dovecot 2.3 behaviour from dovecot-core version 1:2.3.21+dfsg1-2ubuntu6.5 as installed on the reference machine.

What you need: a shell and the Dovecot package that provides doveadm.
Privileges: the discovery steps are read-only and normally need no elevated privileges.
What it will not do: some command pages describe operations that change mailboxes or services, but this guide never runs them.

1. Confirm which installation you are using

Check the executable and package version first. That stops you reading documentation for a different Dovecot installation:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

The doveadm-help(1) page identifies itself as Dovecot v2.3, but the package query is the useful version check here. Do not assume a generic --version option exists: the installed doveadm treats that spelling as an invalid option.

Checkpoint

If command -v finds nothing, stop and install or repair the package through your normal system administration process. Do not copy examples into a script until you know which binary will run.

2. List the available command groups

Run doveadm help without a command name:

$ doveadm help
usage: doveadm [-Dv] [-f <formatter>] <command> [<args>]

         altmove ...
         auth ...
         mailbox ...
         search ...
         user ...
         ...

The real output is longer. It gives a synopsis for most doveadm commands and groups related ones such as mailbox, log and auth. Treat the list as an index, not a description of arguments or side effects.

Tip

On a server with a restricted or incomplete Dovecot setup, startup diagnostics can appear before the usage text. The reference host, for example, reports that it cannot access the stats writer socket, then still prints the command list. That diagnostic is about the local Dovecot runtime, not a new help option. If a script needs to tell documentation output from service diagnostics, capture standard error separately:

doveadm help >/tmp/doveadm-help.out 2>/tmp/doveadm-help.err
status=$?
printf 'help exit status: %s\n' "$status"
sed -n '1,12p' /tmp/doveadm-help.out
sed -n '1,12p' /tmp/doveadm-help.err

This writes temporary diagnostic files. Remove them when you have finished reviewing them:

$ rm -f /tmp/doveadm-help.out /tmp/doveadm-help.err

3. Open the page for a command group

Pass a group name to help. It asks doveadm to display that command's manual page:

$ doveadm help mailbox
DOVEADM-MAILBOX(1)                  Dovecot                 DOVEADM-MAILBOX(1)

NAME
       doveadm-mailbox - Commands related to handling mailboxes

SYNOPSIS
       doveadm [-Dv] [-f formatter] mailbox_cmd [options] [arguments]

Read the synopsis and description before the individual options. The mailbox page draws the safety line clearly: the group can query and modify mailboxes, while help mailbox only displays documentation. The same pattern works for any group or command name in the installed manpage set, for example doveadm help user or doveadm help log.

Checkpoint

Confirm the page's name matches the command you meant. A group name can look plausible and lead to a different operation. If the page is missing or the output is oddly brief, check the package's installed manpages rather than inventing options from memory.

4. Read the global options without applying them

The help page documents three global options for this Dovecot 2.3 command:

-D enables verbosity and debug messages.
-v enables verbosity, including a progress counter.
-o setting=value overrides a configuration setting from /etc/dovecot/dovecot.conf and the userdb for that invocation. Repeat -o to override more than one setting.

Use them only where you understand what they do. A harmless documentation check with verbosity looks like this:

$ doveadm -v help mailbox
DOVEADM-MAILBOX(1)                  Dovecot                 DOVEADM-MAILBOX(1)
... manual page output ...

The option is global, so it goes before help. Diagnostic output varies with the host and configuration, but the manual page you asked for should stay recognisable.

Warning

-o is not a documentation annotation. It changes the configuration the command process sees. Do not paste a production setting into a discovery command just to make an error disappear, and never put secrets directly on a shared shell command line. If you tested an operational command with an override, nothing persistent needs undoing when the process exits, but rerun the command without it and verify the real configuration separately.

5. Move on to an operational command carefully

Once you have the right page, find its command-specific scope. Options such as -u, -A and -F on mailbox-related commands select users. A page may also include create, delete, rename or other state-changing actions. Finding the page does not make those safe to trial on a live service without a backup and a recovery plan.

For an ordinary read-only investigation, save the page or reread it just before running the command:

$ doveadm help mailbox > /tmp/doveadm-mailbox-help.txt
$ sed -n '1,80p' /tmp/doveadm-mailbox-help.txt

Tip

Remove the temporary copy after use. If you need to keep operational evidence, store it under your site's access and retention rules, not as command documentation in a world-readable temporary location.

Done means

Binary identified. command -v doveadm showed the executable you meant to inspect.
Version recorded. The installed package was noted as Dovecot 2.3.21 from dovecot-core.
Groups listed. doveadm help showed the available command groups.
Page opened. doveadm help mailbox displayed the matching detailed manual page.
Globals understood. You know -D, -v and -o are global options, and that -o changes the command's runtime configuration.
Nothing changed. No mailbox, service or persistent Dovecot configuration was touched during discovery.