From e8609bd281a10db7809a3a3edf7a2878e3137745 Mon Sep 17 00:00:00 2001 From: Michael M Slusarz Date: Fri, 13 Dec 2024 22:32:24 -0700 Subject: [PATCH] doveadm: Fill out example information for commands Also add missing text descriptions. --- .github/actions/spelling/expect.txt | 2 + data/doveadm.js | 643 ++++++++++++++++++++++------ lib/data/doveadm.data.js | 3 + lib/doveadm.js | 12 +- 4 files changed, 519 insertions(+), 141 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index c3bd4e489..8348c7e34 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -562,6 +562,7 @@ offenburg OIDC olc oldkey +oldpassword oldpath oldstats onelevel @@ -798,6 +799,7 @@ terabyte testdomain testmbox testpass +testprefix testshared textcat thead diff --git a/data/doveadm.js b/data/doveadm.js index 6cef96428..74122618c 100644 --- a/data/doveadm.js +++ b/data/doveadm.js @@ -1,5 +1,6 @@ /* List of Dovecot doveadm types. */ import { doveadm_arg_types, + doveadm_args_human_timestamp, doveadm_args_query, doveadm_args_usermask, doveadm_flag_types, @@ -93,16 +94,19 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl add': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to add to.`, }, id: { + example: 'acl_id', positional: true, type: doveadm_arg_types.STRING, text: `ID to add to.`, }, right: { + example: ['r', 'w'], positional: true, type: doveadm_arg_types.ARRAY, text: `ACL rights to add.`, @@ -117,6 +121,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl debug': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to query.`, @@ -131,11 +136,13 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl delete': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to delete.`, }, id: { + example: 'acl_id', positional: true, type: doveadm_arg_types.STRING, text: `ID to delete.`, @@ -154,6 +161,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. type: doveadm_arg_types.BOOL, }, mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to query.`, @@ -176,6 +184,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl remove': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to remove rights from.`, @@ -200,6 +209,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl rights': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to show.`, @@ -214,16 +224,19 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'acl set': { args: { mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox to replace rights.`, }, id: { + example: 'acl_id', positional: true, type: doveadm_arg_types.STRING, text: `ID to replace.`, }, right: { + example: ['r', 'w'], positional: true, type: doveadm_arg_types.ARRAY, text: `ACL rights to replace.`, @@ -238,14 +251,14 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'auth cache flush': { args: { 'socket-path': { - //example: `/var/run/dovecot/doveadm-server`, cli: 'a', cli_only: true, + example: `/var/run/dovecot/doveadm-server`, type: doveadm_arg_types.STRING, text: `Path to doveadm socket.`, }, user: { - //example: `foo`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID of user to apply operation to.`, @@ -266,15 +279,18 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'auth-login-socket-path': { cli: 'a', cli_only: true, + example: `/var/run/dovecot/auth-login`, type: doveadm_arg_types.STRING, }, 'auth-master-socket-path': { cli: 'm', cli_only: true, + example: `/var/run/dovecot/auth-master`, type: doveadm_arg_types.STRING, }, 'sasl-mech': { - cli: 'm', + cli: 'A', + example: 'PLAIN', type: doveadm_arg_types.STRING, }, 'auth-info': { @@ -284,17 +300,18 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'master-user': { cli: 'M', + example: 'masteruser', type: doveadm_arg_types.STRING, text: `Master user.`, }, user: { - //example: `foo`, + example: 'username', positional: true, type: doveadm_arg_types.STRING, text: `Login UID.`, }, password: { - //example: `bar`, + example: `password`, positional: true, optional: true, type: doveadm_arg_types.STRING, @@ -308,9 +325,9 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'auth lookup': { args: { 'socket-path': { - //example: `/var/run/dovecot/doveadm-server`, cli: 'a', cli_only: true, + example: `/var/run/dovecot/doveadm-server`, type: doveadm_arg_types.STRING, text: `Path to doveadm socket.`, }, @@ -321,11 +338,12 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, field: { cli: 'f', + example: 'fieldname', type: doveadm_arg_types.STRING, text: `Only return value of this field.`, }, user: { - //example: `foo`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID of user to query.`, @@ -338,14 +356,15 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'auth test': { args: { 'socket-path': { - //example: `/var/run/dovecot/doveadm-server`, cli: 'a', cli_only: true, + example: `/var/run/dovecot/doveadm-server`, type: doveadm_arg_types.STRING, text: `Path to doveadm socket.`, }, 'sasl-mech': { cli: 'A', + example: 'PLAIN', type: doveadm_arg_types.STRING, }, 'auth-info': { @@ -355,17 +374,18 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'master-user': { cli: 'M', + example: 'masteruser', type: doveadm_arg_types.STRING, text: `Master user.` }, user: { - //example: `foo`, + example: 'username', positional: true, type: doveadm_arg_types.STRING, text: `Login UID.` }, password: { - //example: `bar`, + example: `password`, positional: true, optional: true, type: doveadm_arg_types.STRING, @@ -381,82 +401,124 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'full-sync': { cli: 'f', type: doveadm_arg_types.BOOL, + text: `Full sync?`, }, 'purge-remote': { cli: 'P', type: doveadm_arg_types.BOOL, + text: `Purge destination after sync?`, }, 'reverse-sync': { cli: 'R', type: doveadm_arg_types.BOOL, + text: `Do a reverse sync?`, }, 'lock-timeout': { cli: 'l', + example: 60, type: doveadm_arg_types.INTEGER, + text: `Lock timeout for the user (in seconds).`, }, rawlog: { cli: 'r', + example: 'rawlog_name', type: doveadm_arg_types.STRING, + text: `Write rawlog to this file.`, }, mailbox: { cli: 'm', + example: 'INBOX', type: doveadm_arg_types.STRING, + text: `Sync only this mailbox.`, }, 'mailbox-guid': { cli: 'g', + example: 'mailbox_guid', type: doveadm_arg_types.STRING, + text: `Sync only this mailbox GUID.`, }, namespace: { cli: 'n', + example: ['namespace'], type: doveadm_arg_types.ARRAY, + text: `Sync only these namespaces.`, }, 'all-namespaces': { cli: 'N', type: doveadm_arg_types.BOOL, + text: `Sync all namespaces?`, }, 'exclude-mailbox': { cli: 'x', + example: ['excluded_mailbox'], type: doveadm_arg_types.ARRAY, + text: `Exclude these mailbox names/masks.`, }, 'all-mailbox': { cli: 'a', + example: 'VirtualAll', type: doveadm_arg_types.STRING, + text: `The name of the virtual All mailbox.`, }, state: { cli: 's', + example: 'state_string', type: doveadm_arg_types.STRING, + text: `State string of last dsync run.`, }, 'sync-since-time': { cli: 't', + example: '7 days', type: doveadm_arg_types.STRING, + text: `Sync since timestamp. + +` + doveadm_args_human_timestamp, }, 'sync-until-time': { cli: 'e', + example: '1 day', type: doveadm_arg_types.STRING, + text: `Sync until timestamp. + +` + doveadm_args_human_timestamp, }, 'sync-flags': { cli: 'O', + example: '\\deleted', type: doveadm_arg_types.STRING, + text: ` +Sync only mails that have the specified flag. If the flag name begins with +\`-\`, sync all mails except the ones with the specified flag.` }, 'sync-max-size': { cli: 'I', + example: '20M', type: doveadm_arg_types.STRING, + text: `Skip any mails larger than the specified size. + +Format: [[link,settings_types_size]]` }, timeout: { cli: 'T', + example: 60, type: doveadm_arg_types.INTEGER, + text: `Timeout (in seconds).`, }, 'default-destination': { cli: 'd', type: doveadm_arg_types.BOOL, + text: `Use the default destination?`, }, 'legacy-dsync': { cli: 'E', type: doveadm_arg_types.BOOL, + text: `Use legacy dsync?`, }, destination: { positional: true, type: doveadm_arg_types.ARRAY, + text: ` +The synchronized destination. See [[man,doveadm-sync]] for options.` }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, @@ -466,11 +528,13 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'compress connect': { args: { host: { + example: 'hostname', positional: true, type: doveadm_arg_types.STRING, text: `Hostname to connect to.` }, port: { + example: '123', positional: true, optional: true, type: doveadm_arg_types.INTEGER, @@ -484,25 +548,26 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. copy: { args: { 'destination-mailbox': { + example: 'Test', positional: true, type: doveadm_arg_types.STRING, + text: `The destination mailbox.`, }, 'source-user': { - // TODO: key-value with 'user' - positional: true, - optional: true, - type: doveadm_arg_types.STRING, - }, - 'user': { - // TODO: key-value with 'source-user' + example: 'sourceuser', positional: true, optional: true, type: doveadm_arg_types.STRING, + text: ` +Apply the search query to this user's \`mail_location\`. + +For CLI use, this is specified by adding the keyword \`user\` followed by +the source user name, e.g., \`user sourceuser\`.` }, query: doveadm_args_query, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, - man: 'doveadm-move', + man: 'doveadm-copy', text: `Copy messages matching the given search query into another mailbox.`, }, @@ -523,17 +588,19 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'dict get': { args: { user: { - //example: 'foo', cli: 'u', + example: 'username', type: doveadm_arg_types.STRING, text: `uid of user to query.`, }, 'dict-uri': { + example: 'dict_label', positional: true, type: doveadm_arg_types.STRING, text: `URI for dictionary to query.`, }, key: { + example: 'example_key', positional: true, type: doveadm_arg_types.STRING, text: `Key to query.`, @@ -546,22 +613,25 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'dict inc': { args: { user: { - //example: 'foo', cli: 'u', + example: 'username', type: doveadm_arg_types.STRING, text: `uid of user to modify.`, }, 'dict-uri': { + example: 'dict_label', positional: true, type: doveadm_arg_types.STRING, text: `URI for dictionary to query.`, }, key: { + example: 'example_key', positional: true, type: doveadm_arg_types.STRING, text: `Key to query.`, }, difference: { + example: 1, positional: true, type: doveadm_arg_types.INTEGER, text: `The amount to increment.`, @@ -574,8 +644,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'dict iter': { args: { user: { - //example: 'foo', cli: 'u', + example: 'username', type: doveadm_arg_types.STRING, text: `uid of user to query.`, }, @@ -595,11 +665,13 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `List keys that have no value set?`, }, 'dict-uri': { + example: 'dict_label', positional: true, type: doveadm_arg_types.STRING, text: `URI for dictionary to query.`, }, prefix: { + example: 'testprefix', positional: true, type: doveadm_arg_types.STRING, text: `Search only keys with this prefix.`, @@ -612,22 +684,25 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'dict set': { args: { user: { - //example: 'foo', cli: 'u', + example: 'username', type: doveadm_arg_types.STRING, text: `uid of user to query.`, }, 'dict-uri': { + example: 'dict_label', positional: true, type: doveadm_arg_types.STRING, text: `URI for dictionary to query.`, }, key: { + example: 'example_key', positional: true, type: doveadm_arg_types.STRING, text: `Key to query.`, }, value: { + example: 'value', positional: true, type: doveadm_arg_types.STRING, text: `Value to set.`, @@ -640,16 +715,18 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'dict unset': { args: { user: { - //example: 'foo', + example: 'username', type: doveadm_arg_types.STRING, text: `uid of user to query.`, }, 'dict-uri': { + example: 'dict_label', positional: true, type: doveadm_arg_types.STRING, text: `URI for dictionary to query.`, }, key: { + example: 'example_key', positional: true, type: doveadm_arg_types.STRING, text: `Key to unset.`, @@ -663,16 +740,22 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. args: { type: { cli: 't', + example: 'index', type: doveadm_arg_types.STRING, + text: `The type of file to be dumped.`, }, path: { + example: '/path/to/file', positional: true, type: doveadm_arg_types.STRING, + text: `Path to the file specified by the type argument.`, }, args: { + example: ['uid=123'], positional: true, optional: true, type: doveadm_arg_types.ARRAY, + text: `Type specific arguments.`, }, }, man: 'doveadm-dump', @@ -682,11 +765,13 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. exec: { args: { binary: { + example: 'dovecot-lda', positional: true, type: doveadm_arg_types.STRING, text: `The name of an executable located in \`/usr/libexec/dovecot\`.`, }, args: { + example: ['-a arg1', '-b arg2'], positional: true, optional: true, type: doveadm_arg_types.ARRAY, @@ -714,7 +799,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. fetch: { args: { field: { - //example: ['text'], + example: ['text'], type: doveadm_arg_types.ARRAY, text: `Search fields to fetch.`, }, @@ -731,6 +816,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'flags add': { args: { flag: { + example: ['\\flag1'], type: doveadm_arg_types.ARRAY, text: `List of flags to add.`, }, @@ -744,6 +830,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'flags remove': { args: { flag: { + example: ['\\flag1'], type: doveadm_arg_types.ARRAY, text: `List of flags to remove.`, }, @@ -757,6 +844,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'flags replace': { args: { flag: { + example: ['\\flag1'], type: doveadm_arg_types.ARRAY, text: `List of flags to replace with.` }, @@ -784,6 +872,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs copy': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { 'fs-driver': { positional: true, @@ -809,6 +899,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs delete': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { recursive: { cli: 'R', @@ -841,6 +933,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs get': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { 'fs-driver': { positional: true, @@ -863,12 +957,16 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs iter': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { noCache: { + // TODO: Needs to be documented in man page cli: 'C', type: doveadm_arg_types.BOOL }, objectIds: { + // TODO: Needs to be documented in man page cli: 'O', type: doveadm_arg_types.BOOL }, @@ -893,6 +991,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs iter-dirs': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { 'fs-driver': { positional: true, @@ -915,6 +1015,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs metadata': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { 'fs-driver': { positional: true, @@ -936,12 +1038,16 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs put': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { hash: { + // TODO: Needs to be documented in man page cli: 'h', type: doveadm_arg_types.STRING }, metadata: { + // TODO: Needs to be documented in man page cli: 'm', type: doveadm_arg_types.ARRAY }, @@ -971,6 +1077,8 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'fs stat': { + /* No examples in here, as this command's use should not be + * encouraged. */ args: { 'fs-driver': { positional: true, @@ -1013,6 +1121,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'fts optimize': { args: { namespace: { + example: '#shared', positional: true, type: doveadm_arg_types.STRING, text: `Namespace to optimize.`, @@ -1026,6 +1135,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'fts rescan': { args: { namespace: { + example: '#shared', positional: true, type: doveadm_arg_types.STRING, text: `Namespace to rebuild.`, @@ -1036,13 +1146,14 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `Rebuild FTS indexes.`, }, + // TODO: Needs to be documented in man page 'fts tokenize': { args: { language: { type: doveadm_arg_types.STRING, }, text: { - //example: `c’est la vie`, + example: `c’est la vie`, positional: true, type: doveadm_arg_types.ARRAY, text: `String to tokenize.`, @@ -1057,6 +1168,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. args: { 'source-user': { cli: 'U', + example: 'sourceuser', type: doveadm_arg_types.STRING, text: `UID of user to apply import to.`, }, @@ -1066,11 +1178,13 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `Newly created folders are also subscribed to.`, }, 'source-location': { + example: 'maildir:/backup/Maildir', positional: true, type: doveadm_arg_types.STRING, - text: `Location of source mailboxes.`, + text: `Location of source mailbox.`, }, 'dest-parent-mailbox': { + example: 'backup', positional: true, type: doveadm_arg_types.STRING, text: `Destination parent mailbox where to import.`, @@ -1091,10 +1205,12 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'max-recent': { cli: 'n', + example: 10, type: doveadm_arg_types.STRING, text: `Max number of recent mails to index.`, }, 'mailbox-mask': { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox search mask to apply indexing to.`, @@ -1114,15 +1230,21 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, 'max-recent': { cli: 'n', + example: 10, + // TODO: This is treated/documented as an integer value + // (CMD_PARAM_INT64), but is defined as a string in source + // (CMD_PARAM_STR). type: doveadm_arg_types.STRING, text: `The maximum number of \\Recent messages in the mailboxes.`, }, user: { + example: 'username', positional: true, type: doveadm_arg_types.STRING, text: `The user to add.`, }, mailbox: { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `The mailbox to index.`, @@ -1144,6 +1266,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. args: { 'user-mask': doveadm_args_usermask, 'mailbox-mask': { + example: 'Trash', positional: true, optional: true, type: doveadm_arg_types.STRING, @@ -1161,6 +1284,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. type: doveadm_arg_types.BOOL, }, name: { + example: 'instance_name', positional: true, optional: true, type: doveadm_arg_types.STRING, @@ -1173,6 +1297,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'instance remove': { args: { name: { + example: 'instance_name', positional: true, type: doveadm_arg_types.STRING, text: `The instance to remove.`, @@ -1187,21 +1312,24 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'socket-path': { cli: 'a', cli_only: true, + example: '/rundir/anvil', type: doveadm_arg_types.STRING, text: `Anvil socket path.` }, 'passdb-field': { cli: 'f', + example: 'alt_username_field', type: doveadm_arg_types.STRING, - text: `Passdb field.` + text: `Alternative username field to use for kicking.`, }, 'dest-host': { cli: 'h', + example: 'destination_host', type: doveadm_arg_types.STRING, - text: `Destination host.` + text: `Disconnect proxy connections to this destination host.`, }, mask: { - //example: `testuser001`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID mask.`, @@ -1215,6 +1343,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. args: { since: { cli: 'c', + example: 2147483647, type: doveadm_arg_types.INTEGER, text: `Only show errors since this point in time (UNIX timestamp).`, }, @@ -1226,6 +1355,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. 'log find': { args: { 'log-dir': { + example: '/syslogd/write/path', positional: true, optional: true, type: doveadm_arg_types.STRING, @@ -1252,38 +1382,51 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. args: { all: { cli: 'a', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `List or change all fields.`, }, fieldstr: { cli: 'f', - type: doveadm_arg_types.STRING + example: 'field1 field2', + type: doveadm_arg_types.STRING, + text: `List or change these fields (comma/space separated).`, }, 'last-used': { cli: 'l', - type: doveadm_arg_types.INTEGER + example: 2147483647, + type: doveadm_arg_types.INTEGER, + text: `Set last used timestamp.`, }, decision: { cli: 'd', - type: doveadm_arg_types.STRING + example: 'yes', + type: doveadm_arg_types.STRING, + text: `Set field caching decision`, }, mailbox: { + example: ['Trash'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to change cache decisions for.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `List or change caching decisions for field(s).`, }, 'mailbox cache purge': { args: { mailbox: { + example: ['Trash'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to purge index file.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Purge the dovecot.index.cache file.`, }, 'mailbox cache remove': { @@ -1292,25 +1435,32 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Remove matching mails from the cache.`, }, 'mailbox create': { args: { subscriptions: { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Add to subscription list.`, }, guid: { cli: 'g', - type: doveadm_arg_types.STRING + example: 'mailbox-guid', + type: doveadm_arg_types.STRING, + text: `Create mailbox with this GUID.`, }, mailbox: { + example: ['Test'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to create.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Create mailboxes.`, }, 'mailbox cryptokey generate': { @@ -1331,6 +1481,7 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `Force keypair creation, normally keypair is only created if none found.` }, 'mailbox': { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox mask.` @@ -1367,6 +1518,7 @@ to secure it. text: `Operate on user keypair only.` }, 'mailbox': { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox mask.` @@ -1387,6 +1539,7 @@ to secure it. text: `Operate on user keypair only.` }, 'mailbox': { + example: 'INBOX', positional: true, type: doveadm_arg_types.STRING, text: `Mailbox mask.` @@ -1413,6 +1566,7 @@ to secure it. }, 'new-password': { cli: 'n', + example: 'newpassword', type: doveadm_arg_types.STRING, text: `New password.` }, @@ -1423,6 +1577,7 @@ to secure it. }, 'old-password': { cli: 'o', + example: 'oldpassword', type: doveadm_arg_types.STRING, text: `Old password.` }, @@ -1438,163 +1593,210 @@ to secure it. args: { 'require-empty': { cli: 'e', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Require mailboxes to be empty before deleting.`, }, subscriptions: { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Unsubscribe deleted mailboxes.`, }, recursive: { cli: 'r', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Delete mailboxes recursively.`, }, unsafe: { cli: 'Z', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Delete mailboxes as efficiently as possible.`, }, mailbox: { + example: ['Test'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `The mailboxes to delete.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Delete mailboxes.`, }, 'mailbox metadata get': { args: { 'allow-empty-mailbox-name': { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Allow to specify an empty mailbox name string.`, }, mailbox: { + example: 'INBOX', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Target mailbox to query.`, }, key: { + example: 'key', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Metadata key to retrieve.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Get metadata for a mailbox.`, }, 'mailbox metadata list': { args: { 'allow-empty-mailbox-name': { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Allow to specify an empty mailbox name string.`, }, 'prepend-prefix': { cli: 'p', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Prepend the prefix to results.`, }, mailbox: { + example: 'INBOX', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Target mailbox to query.`, }, 'key-prefix': { + example: 'key-prefix', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The key prefix to look for.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `List metadata for a mailbox.`, }, 'mailbox metadata set': { args: { 'allow-empty-mailbox-name': { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Allow to specify an empty mailbox name string.`, }, mailbox: { + example: 'INBOX', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Target mailbox.`, }, key: { + example: 'key', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The key to add.`, }, value: { + example: 'value', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The value to add.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Set metadata for a mailbox.`, }, 'mailbox metadata unset': { args: { 'allow-empty-mailbox-name': { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Allow to specify an empty mailbox name string.`, }, mailbox: { + example: 'INBOX', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Target mailbox.`, }, key: { + example: 'key', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The key to delete.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Unset metadata for a mailbox.`, }, 'mailbox list': { args: { mutf7: { cli: '7', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Lists mailboxes with mUTF-7 encoding.`, }, utf8: { cli: '8', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Lists mailboxes with UTF-8 encoding.`, }, subscriptions: { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Only list subscribed mailboxes?`, }, 'mailbox-mask': { + example: ['INBOX'], positional: true, optional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `A list of mailbox masks to list.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Get list of existing mailboxes.`, }, 'mailbox mutf7': { args: { toUtf8: { cli: '7', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Mailbox is in mUTF-7 format.`, }, fromUtf8: { cli: '8', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Mailbox is in UTF-8 format.`, }, name: { + example: ['Test'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailbox names to convert.`, }, }, man: 'doveadm-mailbox', + text: `Convert mailbox names from mUTF-7 to UTF-8.`, }, 'mailbox path': { args: { type: { cli: 't', + example: 'index', type: doveadm_arg_types.STRING, text: `Mailbox path type.` }, mailbox: { + example: ['INBOX'], positional: true, type: doveadm_arg_types.ARRAY, text: `Mailbox name to query.` @@ -1602,121 +1804,151 @@ to secure it. }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Returns filesystem paths for the mailboxes.`, }, 'mailbox rename': { args: { subscriptions: { cli: 's', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Unsubscribe old mailbox and subscribe new mailbox.`, }, mailbox: { + example: 'OldName', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The source mailbox name.`, }, 'new-name': { + example: 'NewName', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The destination mailbox name.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Rename mailbox.`, }, 'mailbox status': { args: { 'total-sum': { cli: 't', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Sum values of status fields.`, }, field: { cli: 'f', + example: ['all'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Fields that should be shown.`, }, 'mailbox-mask': { + example: ['INBOX'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to query.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Show status of mailboxes.`, }, 'mailbox subscribe': { args: { mailbox: { + example: ['Test'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to subscribe to.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Subscribe to mailboxes.`, }, 'mailbox unsubscribe': { args: { mailbox: { + example: ['Test'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Mailboxes to unsubscribe from.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Unsubscribe from mailboxes.`, }, 'mailbox update': { + /* No examples in here, because this command's use should not be + * encouraged. */ args: { 'mailbox-guid': { cli: 'g', - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Mailbox GUID.`, }, 'uid-validity': { cli: 'V', - type: doveadm_arg_types.INTEGER + type: doveadm_arg_types.INTEGER, + text: `UID validity.`, }, 'min-next-uid': { cli: 'N', - type: doveadm_arg_types.INTEGER + type: doveadm_arg_types.INTEGER, + text: `Minimum NEXTUID.`, }, 'min-first-recent-uid': { cli: 'R', - type: doveadm_arg_types.INTEGER + type: doveadm_arg_types.INTEGER, + text: `First recent UID.`, }, 'min-highest-modseq': { cli: 'H', - type: doveadm_arg_types.INTEGER + type: doveadm_arg_types.INTEGER, + text: `Minimum highest MODSEQ.`, }, 'min-highest-private-modseq': { cli: 'P', - type: doveadm_arg_types.INTEGER + type: doveadm_arg_types.INTEGER, + text: `Minimum highest private MODSEQ.`, }, mailbox: { positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Mailbox to update.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-mailbox', + text: `Set internal mailbox metadata.`, }, move: { args: { 'destination-mailbox': { + example: 'Test', positional: true, type: doveadm_arg_types.STRING, + text: `The destination mailbox.`, }, 'source-user': { - // TODO: key-value with 'user' - positional: true, - optional: true, - type: doveadm_arg_types.STRING, - }, - 'user': { - // TODO: key-value with 'source-user' + example: 'sourceuser', positional: true, optional: true, type: doveadm_arg_types.STRING, + text: ` +Apply the search query to this user's \`mail_location\`. + +For CLI use, this is specified by adding the keyword \`user\` followed by +the source user name, e.g., \`user sourceuser\`.` }, query: doveadm_args_query, }, @@ -1729,12 +1961,15 @@ to secure it. 'socket-path': { cli: 'a', cli_only: true, + example: '/rundir/anvil', type: doveadm_arg_types.STRING, text: `Anvil socket path.` }, netmask: { + example: '127.0.0.0/8', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Filter output by netmask.`, }, }, man: 'doveadm-penalty', @@ -1743,9 +1978,11 @@ to secure it. 'process status': { args: { service: { + example: ['stats'], positional: true, optional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Filter output to only these services.`, }, }, man: 'doveadm-process-status', @@ -1756,21 +1993,24 @@ to secure it. 'socket-path': { cli: 'a', cli_only: true, + example: '/rundir/anvil', type: doveadm_arg_types.STRING, text: `Anvil socket path.` }, 'passdb-field': { cli: 'f', + example: 'alt_username_field', type: doveadm_arg_types.STRING, - text: `Passdb field.` + text: `Alternative username field to use for kicking.`, }, 'dest-host': { cli: 'h', + example: 'destination_host', type: doveadm_arg_types.STRING, - text: `Destination host.` + text: `Disconnect proxy connections to this destination host.`, }, mask: { - //example: `testuser001`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID mask.`, @@ -1790,20 +2030,23 @@ to secure it. 'socket-path': { cli: 'a', cli_only: true, + example: '/rundir/anvil', type: doveadm_arg_types.STRING, text: `Anvil socket path.` }, 'separate-connections': { cli: '1', type: doveadm_arg_types.BOOL, + text: `Output one entry per user/connection.`, }, 'passdb-field': { cli: 'f', + example: 'alt_username_field', type: doveadm_arg_types.STRING, - text: `Passdb field.` + text: `Alternative username field to use for listing.`, }, mask: { - //example: `testuser001`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID mask.`, @@ -1830,40 +2073,54 @@ returned.`, args: {}, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-purge', + text: `Remove all messages with refcount=0 from a user's mail storage.`, }, pw: { args: { list: { cli: 'l', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `List all supported password schemes.`, }, plaintext: { cli: 'p', - type: doveadm_arg_types.STRING + example: 'password', + type: doveadm_arg_types.STRING, + text: `Plaintext password.`, }, rounds: { cli: 'r', - type: doveadm_arg_types.INTEGER + example: 5000, + type: doveadm_arg_types.INTEGER, + text: `Number of encryption rounds.`, }, scheme: { cli: 's', - type: doveadm_arg_types.STRING + example: 'CRYPT', + type: doveadm_arg_types.STRING, + text: `The password scheme to use.`, }, 'test-hash': { cli: 't', - type: doveadm_arg_types.STRING + example: 'password_hash', + type: doveadm_arg_types.STRING, + text: `Test if hash matches password (e.g., \`plaintext\` argument).`, }, user: { cli: 'u', - type: doveadm_arg_types.STRING + example: 'username', + type: doveadm_arg_types.STRING, + text: `Username to use for schemes that require one.`, }, 'reverse-verify': { cli: 'V', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Internally verify hashed password.`, }, }, man: 'doveadm-pw', + text: `Generate password hashes.`, }, 'quota get': { @@ -1871,6 +2128,7 @@ returned.`, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'quota', man: 'doveadm-quota', + text: `Display current quota usage.`, }, 'quota recalc': { @@ -1878,6 +2136,7 @@ returned.`, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'quota', man: 'doveadm-quota', + text: `Recalculate current quota usage.`, }, 'rebuild attachments': { @@ -1886,34 +2145,45 @@ returned.`, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-rebuild', + text: `Rebuild attachment detection information in index.`, }, reload: { args: {}, man: 'doveadm', + text: `Reload Dovecot configuration.`, }, save: { args: { mailbox: { cli: 'm', - type: doveadm_arg_types.STRING + example: 'Test', + type: doveadm_arg_types.STRING, + text: `Save in this mailbox instead of INBOX.`, }, uid: { cli: 'U', - type: doveadm_arg_types.INTEGER + example: 1000, + type: doveadm_arg_types.INTEGER, + text: `Save using this UID.`, }, guid: { cli: 'g', - type: doveadm_arg_types.STRING + example: 1000, + type: doveadm_arg_types.STRING, + text: `Save using this GID.`, }, 'received-date': { cli: 'r', - type: doveadm_arg_types.STRING + example: `2007-04-13`, + type: doveadm_arg_types.STRING, + text: `Save with this as the received date.`, }, file: { positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The message data to save.`, }, }, added: { @@ -1922,6 +2192,7 @@ returned.`, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-save', + text: `Save messages to a mailbox.`, }, search: { @@ -1930,117 +2201,146 @@ returned.`, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, man: 'doveadm-search', + text: `Find matching messages in mailbox.`, }, 'service status': { args: { service: { + example: ['name'], positional: true, optional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `Filter output to only these services.`, }, }, man: 'doveadm-service-status', + text: `Show information about Dovecot services.`, }, 'service stop': { args: { service: { + example: ['stats'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `The list of services to stop.`, }, }, - // TODO: Needs man page + man: 'doveadm-service-stop', + text: `Stop Dovecot services.` }, 'sieve activate': { args: { scriptname: { + example: 'scriptname', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The script name to mark as active.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Mark active Sieve script.`, }, 'sieve deactivate': { args: {}, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Deactivate Sieve script.`, }, 'sieve delete': { args: { 'ignore-active': { cli: 'a', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `If set, allows the active script to be deleted.`, }, scriptname: { + example: ['scriptname'], positional: true, - type: doveadm_arg_types.ARRAY + type: doveadm_arg_types.ARRAY, + text: `The list of scripts to delete.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Delete Sieve scripts.`, }, 'sieve get': { args: { scriptname: { + example: 'scriptname', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The script to retrieve.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Retrieve a Sieve script.`, }, 'sieve list': { args: {}, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `List Sieve scripts.`, }, 'sieve put': { args: { activate: { cli: 'a', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Mark script as active.`, }, scriptname: { + example: 'scriptname', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The script to retrieve.`, }, file: { positional: true, - type: doveadm_arg_types.ISTREAM + type: doveadm_arg_types.ISTREAM, + text: `The script to add.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Add Sieve script to storage.`, }, 'sieve rename': { args: { oldname: { + example: 'old_scriptname', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The old scriptname.`, }, newname: { + example: 'new_scriptname', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The new scriptname.`, }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, plugin: 'sieve', - man: 'doveadm-sieve' + man: 'doveadm-sieve', + text: `Rename Sieve script.`, }, /* Deprecated. */ @@ -2057,6 +2357,7 @@ returned.`, }, }, + // TODO: Fix man page TODOs 'stats add': { args: { exporter: { @@ -2075,15 +2376,18 @@ returned.`, type: doveadm_arg_types.STRING }, name: { + example: 'metric_name', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Metric name.`, }, filter: { positional: true, type: doveadm_arg_types.STRING }, }, - man: 'doveadm-stats' + man: 'doveadm-stats', + text: `Add metrics to statistics.`, }, 'stats dump': { @@ -2091,38 +2395,48 @@ returned.`, socketPath: { cli: 's', cli_only: true, - type: doveadm_arg_types.STRING + example: '/path/to/stats', + type: doveadm_arg_types.STRING, + text: `Path to socket path.`, }, reset: { cli: 'r', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Reset stats after dumping.`, }, fields: { cli: 'f', - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `Stats fields to return.`, }, }, - man: 'doveadm-stats' + man: 'doveadm-stats', + text: `Output statistics.`, }, 'stats remove': { args: { name: { + example: 'metric_name', positional: true, - type: doveadm_arg_types.STRING + type: doveadm_arg_types.STRING, + text: `The metric to remove.`, }, }, - man: 'doveadm-stats' + man: 'doveadm-stats', + text: `Remove metrics from statistics.`, }, 'stats reopen': { args: {}, - man: 'doveadm-stats' + man: 'doveadm-stats', + text: `Reopen file exporter files.`, }, 'stop': { args: {}, - // TODO: man page needed + man: 'doveadm', + text: `Stop Dovecot.`, }, sync: { @@ -2130,90 +2444,128 @@ returned.`, 'full-sync': { cli: 'f', type: doveadm_arg_types.BOOL, + text: `Do full synchronization.`, }, 'purge-remote': { cli: 'P', type: doveadm_arg_types.BOOL, + text: `Run a purge for remote after sync.`, }, 'reverse-sync': { cli: 'R', type: doveadm_arg_types.BOOL, + text: `Do a reverse sync.`, }, 'lock-timeout': { cli: 'l', + example: 60, type: doveadm_arg_types.INTEGER, + text: `Lock timeout (in seconds).`, }, rawlog: { cli: 'r', + example: '/tmp/rawlog', type: doveadm_arg_types.STRING, + text: `Rawlog path.`, }, mailbox: { cli: 'm', + example: 'INBOX', type: doveadm_arg_types.STRING, + text: `Only sync this mailbox.`, }, 'mailbox-guid': { cli: 'g', + example: 'mailbox-guid', type: doveadm_arg_types.STRING, + text: `Only sync this mailbox (by GUID).`, }, namespace: { cli: 'n', + example: ['#shared'], type: doveadm_arg_types.ARRAY, + text: `Only sync this list of namespaces.`, }, 'all-namespaces': { cli: 'N', type: doveadm_arg_types.BOOL, + text: `Sync all namespaces.`, }, 'exclude-mailbox': { cli: 'x', + example: ['Spam'], type: doveadm_arg_types.ARRAY, + text: `Exclude these mailboxes.`, }, 'all-mailbox': { cli: 'a', + example: 'AllMailbox', type: doveadm_arg_types.STRING, + text: `Name for the "All Mails" virtual mailbox.`, }, state: { cli: 's', + example: 'state_string', type: doveadm_arg_types.STRING, + text: `Use stateful sync.`, }, 'sync-since-time': { cli: 't', + example: '2023-04-13', type: doveadm_arg_types.STRING, + text: `Skip mails older than this date.`, }, 'sync-until-time': { cli: 'e', + example: '2023-10-21', type: doveadm_arg_types.STRING, + text: `Skip mails newer than this date.`, }, 'sync-flags': { cli: 'O', + example: '\\Flagged', type: doveadm_arg_types.STRING, + text: `Sync only mails with this flag.`, }, 'sync-max-size': { cli: 'I', + example: '10M', type: doveadm_arg_types.STRING, + text: `Skip mails larger than this size.`, }, timeout: { cli: 'T', + example: 600, type: doveadm_arg_types.INTEGER, + text: `Timeout for stalled I/O operations.`, }, 'default-destination': { cli: 'd', type: doveadm_arg_types.BOOL, + text: `Use the default destination.`, }, + /* This is not documented in man page, so it is hidden here. 'legacy-dsync': { cli: 'E', type: doveadm_arg_types.BOOL, + text: `Do full synchronization.`, }, + */ 'oneway-sync': { cli: '1', type: doveadm_arg_types.BOOL, + text: `Do one-way synchronization.`, }, destination: { + example: ['maildir:~/Maildir'], positional: true, type: doveadm_arg_types.ARRAY, + text: `Sync destinations.` }, }, flags: doveadm_flag_types.USER | doveadm_flag_types.USERFILE, - man: 'doveadm-sync' + man: 'doveadm-sync', + text: `Dovecot's mailbox synchronization utility.`, }, user: { @@ -2221,28 +2573,36 @@ returned.`, 'socket-path': { cli: 'a', cli_only: true, + example: `/var/run/dovecot/doveadm-server`, type: doveadm_arg_types.STRING, text: `userdb socket path` }, 'auth-info': { cli: 'x', - type: doveadm_arg_types.ARRAY + example: ['service=imap'], + type: doveadm_arg_types.ARRAY, + text: `Additional conditions for auth lookup.`, }, field: { cli: 'f', - type: doveadm_arg_types.STRING + example: 'userdb_field', + type: doveadm_arg_types.STRING, + text: `Only show value of this field.`, }, + // TODO: Needs documentation in man file 'expand-field': { cli: 'e', type: doveadm_arg_types.STRING }, 'userdb-only': { cli: 'u', - type: doveadm_arg_types.BOOL + type: doveadm_arg_types.BOOL, + text: `Only show values from userdb.`, }, 'user-mask': doveadm_args_usermask, }, man: 'doveadm-user', + text: `Lookup user in Dovecot's userdbs.`, }, who: { @@ -2250,20 +2610,23 @@ returned.`, 'socket-path': { cli: 'a', cli_only: true, + example: '/rundir/anvil', type: doveadm_arg_types.STRING, text: `Anvil socket path.` }, 'separate-connections': { cli: '1', type: doveadm_arg_types.BOOL, + text: `Output one entry per user/connection.`, }, 'passdb-field': { cli: 'f', + example: 'alt_username_field', type: doveadm_arg_types.STRING, - text: `Passdb field.` + text: `Alternative username field to use for lookup.`, }, mask: { - //example: `testuser001`, + example: 'username', positional: true, type: doveadm_arg_types.ARRAY, text: `UID mask.`, diff --git a/lib/data/doveadm.data.js b/lib/data/doveadm.data.js index d783c8b14..76a751149 100644 --- a/lib/data/doveadm.data.js +++ b/lib/data/doveadm.data.js @@ -7,16 +7,19 @@ import slugify from '@sindresorhus/slugify' const doveadm_userargs = { 'all-users': { cli: 'A', + example: false, type: doveadm_arg_types.BOOL, text: `Apply operation to all users.` }, 'socket-path': { cli: 'S', + example: '/var/run/dovecot/doveadm-server', type: doveadm_arg_types.STRING, text: `Path to doveadm socket.` }, user: { cli: 'u', + example: 'username', type: doveadm_arg_types.STRING, text: `UID of user to apply operation to.`, }, diff --git a/lib/doveadm.js b/lib/doveadm.js index b6367db44..7a2e0ed95 100644 --- a/lib/doveadm.js +++ b/lib/doveadm.js @@ -23,18 +23,28 @@ export const doveadm_response_types = { } export const doveadm_args_query = { - //example: ['mailbox', 'INBOX/myfoldertoo', 'savedbefore', 'since', '30d'], + example: ['mailbox', 'INBOX/myfoldertoo', 'savedbefore', 'since', '30d'], positional: true, type: doveadm_arg_types.SEARCH_QUERY, text: `Search query to apply.`, } export const doveadm_args_usermask = { + example: 'username', positional: true, type: doveadm_arg_types.STRING, text: `User Mask.` } +export const doveadm_args_human_timestamp = ` +Allowable formats: + +* yyyy-mm-dd (non-UTC), +* IMAP date ("dd-mm-yyyy"; see [[rfc,3501]]) (non-UTC) +* IMAP date-time ("dd-mm-yyy HH:MM:SS +0000; see [[rfc,3501]]) (UTC supported) +* Unix timestamp (UTC supported) +* Interval ("n days", UTC supported)` + /* Generate command line string for doveadm. */ export function getDoveadmCmdLine(args) { let ret = ''