completion: add command option descriptions

Add `desc:""` struct field tags in all command arguments where it makes
sense.

The description values will be returned along with completion choices.

Implements: https://todo.sr.ht/~rjarry/aerc/271
Signed-off-by: Robin Jarry <robin@jarry.cc>
Tested-by: Bojan Gabric <bojan@bojangabric.com>
Tested-by: Jason Cox <me@jasoncarloscox.com>
Acked-by: Tim Culverhouse <tim@timculverhouse.com>

58 files changed, 155 insertions, 166 deletions

diff --git a/commands/account/align.go b/commands/account/align.go
index 83bb5b64..2c65b556 100644
--- a/commands/account/align.go
+++ b/commands/account/align.go
@@ -9,7 +9,7 @@ import (
 )
 
 type Align struct {
-	Pos app.AlignPosition `opt:"pos" metavar:"top|center|bottom" action:"ParsePos" complete:"CompletePos"`
+	Pos app.AlignPosition `opt:"pos" metavar:"top|center|bottom" action:"ParsePos" complete:"CompletePos" desc:"Position."`
 }
 
 func init() {
diff --git a/commands/account/cf.go b/commands/account/cf.go
index 3cce37a3..8ec327ae 100644
--- a/commands/account/cf.go
+++ b/commands/account/cf.go
@@ -14,8 +14,8 @@ import (
 )
 
 type ChangeFolder struct {
-	Account bool   `opt:"-a"`
-	Folder  string `opt:"..." complete:"CompleteFolderAndNotmuch"`
+	Account string `opt:"-a" complete:"CompleteAccount" desc:"Change to specified account."`
+	Folder  string `opt:"..." complete:"CompleteFolderAndNotmuch" desc:"Folder name."`
 }
 
 func init() {
@@ -34,20 +34,12 @@ func (ChangeFolder) Aliases() []string {
 	return []string{"cf"}
 }
 
-func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
-	var acct *app.AccountView
+func (c *ChangeFolder) CompleteAccount(arg string) []string {
+	return commands.FilterList(app.AccountNames(), arg, commands.QuoteSpace)
+}
 
-	args := opt.LexArgs(c.Folder)
-	if c.Account {
-		accountName, _ := args.ArgSafe(0)
-		if args.Count() <= 1 && arg == accountName {
-			return commands.FilterList(
-				app.AccountNames(), arg, commands.QuoteSpace)
-		}
-		acct, _ = app.Account(accountName)
-	} else {
-		acct = app.SelectedAccount()
-	}
+func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
+	acct := app.SelectedAccount()
 	if acct == nil {
 		return nil
 	}
@@ -77,15 +69,12 @@ func (c *ChangeFolder) CompleteFolderAndNotmuch(arg string) []string {
 func (c ChangeFolder) Execute([]string) error {
 	var target string
 	var acct *app.AccountView
+	var err error
 
 	args := opt.LexArgs(c.Folder)
 
-	if c.Account {
-		names, err := args.ShiftSafe(1)
-		if err != nil {
-			return errors.New("<account> is required. Usage: cf -a <account> <folder>")
-		}
-		acct, err = app.Account(names[0])
+	if c.Account != "" {
+		acct, err = app.Account(c.Account)
 		if err != nil {
 			return err
 		}
diff --git a/commands/account/clear.go b/commands/account/clear.go
index e16b563a..d45c5201 100644
--- a/commands/account/clear.go
+++ b/commands/account/clear.go
@@ -9,7 +9,7 @@ import (
 )
 
 type Clear struct {
-	Selected bool `opt:"-s"`
+	Selected bool `opt:"-s" desc:"Select first message after clearing."`
 }
 
 func init() {
diff --git a/commands/account/compose.go b/commands/account/compose.go
index 9eeb339b..5e5d3e0f 100644
--- a/commands/account/compose.go
+++ b/commands/account/compose.go
@@ -16,10 +16,10 @@ import (
 )
 
 type Compose struct {
-	Headers  string `opt:"-H" action:"ParseHeader"`
-	Template string `opt:"-T" complete:"CompleteTemplate"`
-	Edit     bool   `opt:"-e"`
-	NoEdit   bool   `opt:"-E"`
+	Headers  string `opt:"-H" action:"ParseHeader" desc:"Add the specified header to the message."`
+	Template string `opt:"-T" complete:"CompleteTemplate" desc:"Template name."`
+	Edit     bool   `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit   bool   `opt:"-E" desc:"Force [compose].edit-headers = false."`
 	Body     string `opt:"..." required:"false"`
 }
 
diff --git a/commands/account/export-mbox.go b/commands/account/export-mbox.go
index fed8568e..529dbae0 100644
--- a/commands/account/export-mbox.go
+++ b/commands/account/export-mbox.go
@@ -19,7 +19,7 @@ import (
 )
 
 type ExportMbox struct {
-	Filename string `opt:"filename" complete:"CompleteFilename"`
+	Filename string `opt:"filename" complete:"CompleteFilename" desc:"Output file path."`
 }
 
 func init() {
diff --git a/commands/account/import-mbox.go b/commands/account/import-mbox.go
index 946098e5..85101bc2 100644
--- a/commands/account/import-mbox.go
+++ b/commands/account/import-mbox.go
@@ -19,7 +19,7 @@ import (
 )
 
 type ImportMbox struct {
-	Filename string `opt:"filename" complete:"CompleteFilename"`
+	Filename string `opt:"filename" complete:"CompleteFilename" desc:"Input file path."`
 }
 
 func init() {
diff --git a/commands/account/mkdir.go b/commands/account/mkdir.go
index cf8763be..76b8f2f8 100644
--- a/commands/account/mkdir.go
+++ b/commands/account/mkdir.go
@@ -11,7 +11,7 @@ import (
 )
 
 type MakeDir struct {
-	Folder string `opt:"folder" complete:"CompleteFolder"`
+	Folder string `opt:"folder" complete:"CompleteFolder" desc:"Folder name."`
 }
 
 func init() {
diff --git a/commands/account/query.go b/commands/account/query.go
index da8a8c06..c30b2c78 100644
--- a/commands/account/query.go
+++ b/commands/account/query.go
@@ -11,10 +11,10 @@ import (
 )
 
 type Query struct {
-	Account string `opt:"-a" complete:"CompleteAccount"`
-	Name    string `opt:"-n"`
-	Force   bool   `opt:"-f"`
-	Query   string `opt:"..." complete:"CompleteNotmuch"`
+	Account string `opt:"-a" complete:"CompleteAccount" desc:"Account name."`
+	Name    string `opt:"-n" desc:"Force name of virtual folder."`
+	Force   bool   `opt:"-f" desc:"Replace existing query if any."`
+	Query   string `opt:"..." complete:"CompleteNotmuch" desc:"Notmuch query."`
 }
 
 func init() {
diff --git a/commands/account/recover.go b/commands/account/recover.go
index 625ac122..7f5b27f5 100644
--- a/commands/account/recover.go
+++ b/commands/account/recover.go
@@ -13,10 +13,10 @@ import (
 )
 
 type Recover struct {
-	Force  bool   `opt:"-f"`
-	Edit   bool   `opt:"-e"`
-	NoEdit bool   `opt:"-E"`
-	File   string `opt:"file" complete:"CompleteFile"`
+	Force  bool   `opt:"-f" desc:"Delete recovered file after opening the composer."`
+	Edit   bool   `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool   `opt:"-E" desc:"Force [compose].edit-headers = false."`
+	File   string `opt:"file" complete:"CompleteFile" desc:"Recover file path."`
 }
 
 func init() {
diff --git a/commands/account/rmdir.go b/commands/account/rmdir.go
index 852d717b..b7a99c18 100644
--- a/commands/account/rmdir.go
+++ b/commands/account/rmdir.go
@@ -13,8 +13,8 @@ import (
 )
 
 type RemoveDir struct {
-	Force  bool   `opt:"-f"`
-	Folder string `opt:"folder" complete:"CompleteFolder" required:"false"`
+	Force  bool   `opt:"-f" desc:"Remove the directory even if it contains messages."`
+	Folder string `opt:"folder" complete:"CompleteFolder" required:"false" desc:"Folder name."`
 }
 
 func init() {
diff --git a/commands/account/search.go b/commands/account/search.go
index 5dde3322..f64bcf91 100644
--- a/commands/account/search.go
+++ b/commands/account/search.go
@@ -19,20 +19,20 @@ import (
 )
 
 type SearchFilter struct {
-	Read         bool                 `opt:"-r" action:"ParseRead"`
-	Unread       bool                 `opt:"-u" action:"ParseUnread"`
-	Body         bool                 `opt:"-b"`
-	All          bool                 `opt:"-a"`
-	UseExtension bool                 `opt:"-e"`
-	Headers      textproto.MIMEHeader `opt:"-H" action:"ParseHeader" metavar:"<header>:<value>"`
-	WithFlags    models.Flags         `opt:"-x" action:"ParseFlag" complete:"CompleteFlag"`
-	WithoutFlags models.Flags         `opt:"-X" action:"ParseNotFlag" complete:"CompleteFlag"`
-	To           []string             `opt:"-t" action:"ParseTo" complete:"CompleteAddress"`
-	From         []string             `opt:"-f" action:"ParseFrom" complete:"CompleteAddress"`
-	Cc           []string             `opt:"-c" action:"ParseCc" complete:"CompleteAddress"`
-	StartDate    time.Time            `opt:"-d" action:"ParseDate" complete:"CompleteDate"`
+	Read         bool                 `opt:"-r" action:"ParseRead" desc:"Search for read messages."`
+	Unread       bool                 `opt:"-u" action:"ParseUnread" desc:"Search for unread messages."`
+	Body         bool                 `opt:"-b" desc:"Search in the body of the messages."`
+	All          bool                 `opt:"-a" desc:"Search in the entire text of the messages."`
+	UseExtension bool                 `opt:"-e" desc:"Use custom search backend extension."`
+	Headers      textproto.MIMEHeader `opt:"-H" action:"ParseHeader" metavar:"<header>:<value>" desc:"Search for messages with the specified header."`
+	WithFlags    models.Flags         `opt:"-x" action:"ParseFlag" complete:"CompleteFlag" desc:"Search messages with specified flag."`
+	WithoutFlags models.Flags         `opt:"-X" action:"ParseNotFlag" complete:"CompleteFlag" desc:"Search messages without specified flag."`
+	To           []string             `opt:"-t" action:"ParseTo" complete:"CompleteAddress" desc:"Search for messages To:<address>."`
+	From         []string             `opt:"-f" action:"ParseFrom" complete:"CompleteAddress" desc:"Search for messages From:<address>."`
+	Cc           []string             `opt:"-c" action:"ParseCc" complete:"CompleteAddress" desc:"Search for messages Cc:<address>."`
+	StartDate    time.Time            `opt:"-d" action:"ParseDate" complete:"CompleteDate" desc:"Search for messages within a particular date range."`
 	EndDate      time.Time
-	Terms        string `opt:"..." required:"false" complete:"CompleteTerms"`
+	Terms        string `opt:"..." required:"false" complete:"CompleteTerms" desc:"Search term."`
 }
 
 func init() {
diff --git a/commands/account/sort.go b/commands/account/sort.go
index 16060aa0..b381548c 100644
--- a/commands/account/sort.go
+++ b/commands/account/sort.go
@@ -13,8 +13,8 @@ import (
 type Sort struct {
 	Unused struct{} `opt:"-"`
 	// these fields are only used for completion
-	Reverse  bool     `opt:"-r"`
-	Criteria []string `opt:"criteria" complete:"CompleteCriteria"`
+	Reverse  bool     `opt:"-r" desc:"Sort in the reverse order."`
+	Criteria []string `opt:"criteria" complete:"CompleteCriteria" desc:"Sort criterion."`
 }
 
 func init() {
diff --git a/commands/account/view.go b/commands/account/view.go
index 0e3ca09c..72f62b51 100644
--- a/commands/account/view.go
+++ b/commands/account/view.go
@@ -13,8 +13,8 @@ import (
 )
 
 type ViewMessage struct {
-	Peek       bool `opt:"-p"`
-	Background bool `opt:"-b"`
+	Peek       bool `opt:"-p" desc:"Peek message without marking it as read."`
+	Background bool `opt:"-b" desc:"Open message in a background tab."`
 }
 
 func init() {
diff --git a/commands/cd.go b/commands/cd.go
index 27333807..4a2fea06 100644
--- a/commands/cd.go
+++ b/commands/cd.go
@@ -11,7 +11,7 @@ import (
 var previousDir string
 
 type ChangeDirectory struct {
-	Target string `opt:"directory" default:"~" complete:"CompleteTarget"`
+	Target string `opt:"directory" default:"~" complete:"CompleteTarget" desc:"Target directory."`
 }
 
 func init() {
diff --git a/commands/compose/attach.go b/commands/compose/attach.go
index f811f5a8..14739127 100644
--- a/commands/compose/attach.go
+++ b/commands/compose/attach.go
@@ -21,9 +21,9 @@ import (
 )
 
 type Attach struct {
-	Menu bool   `opt:"-m"`
-	Name string `opt:"-r"`
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Menu bool   `opt:"-m" desc:"Select files from file-picker-cmd."`
+	Name string `opt:"-r" desc:"<name> <cmd...>: Generate attachment from command output."`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"Attachment file path."`
 	Args string `opt:"..." required:"false"`
 }
 
diff --git a/commands/compose/cc-bcc.go b/commands/compose/cc-bcc.go
index a3c1c188..ec47afe6 100644
--- a/commands/compose/cc-bcc.go
+++ b/commands/compose/cc-bcc.go
@@ -6,7 +6,7 @@ import (
 )
 
 type CC struct {
-	Recipients string `opt:"recipients" complete:"CompleteAddress"`
+	Recipients string `opt:"recipients" complete:"CompleteAddress" desc:"Recipient from address book."`
 }
 
 func init() {
diff --git a/commands/compose/detach.go b/commands/compose/detach.go
index ddf2e24f..5420d382 100644
--- a/commands/compose/detach.go
+++ b/commands/compose/detach.go
@@ -11,7 +11,7 @@ import (
 )
 
 type Detach struct {
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"Attachment file path."`
 }
 
 func init() {
diff --git a/commands/compose/edit.go b/commands/compose/edit.go
index f02848b7..117afe32 100644
--- a/commands/compose/edit.go
+++ b/commands/compose/edit.go
@@ -9,8 +9,8 @@ import (
 )
 
 type Edit struct {
-	Edit   bool `opt:"-e"`
-	NoEdit bool `opt:"-E"`
+	Edit   bool `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool `opt:"-E" desc:"Force [compose].edit-headers = false."`
 }
 
 func init() {
diff --git a/commands/compose/header.go b/commands/compose/header.go
index 64c1c37d..fa60f59f 100644
--- a/commands/compose/header.go
+++ b/commands/compose/header.go
@@ -9,9 +9,9 @@ import (
 )
 
 type Header struct {
-	Force  bool   `opt:"-f"`
-	Remove bool   `opt:"-d"`
-	Name   string `opt:"name" complete:"CompleteHeaders"`
+	Force  bool   `opt:"-f" desc:"Overwrite any existing header."`
+	Remove bool   `opt:"-d" desc:"Remove the header instead of adding it."`
+	Name   string `opt:"name" complete:"CompleteHeaders" desc:"Header name."`
 	Value  string `opt:"..." required:"false"`
 }
 
diff --git a/commands/compose/multipart.go b/commands/compose/multipart.go
index 87f4d030..34ab3af6 100644
--- a/commands/compose/multipart.go
+++ b/commands/compose/multipart.go
@@ -9,8 +9,8 @@ import (
 )
 
 type Multipart struct {
-	Remove bool   `opt:"-d"`
-	Mime   string `opt:"mime" metavar:"<mime/type>" complete:"CompleteMime"`
+	Remove bool   `opt:"-d" desc:"Remove the specified mime/type."`
+	Mime   string `opt:"mime" metavar:"<mime/type>" complete:"CompleteMime" desc:"MIME/type name."`
 }
 
 func init() {
@@ -18,7 +18,7 @@ func init() {
 }
 
 func (Multipart) Description() string {
-	return "Convert the message to multipart with the given mime-type part."
+	return "Convert the message to multipart with the given mime/type part."
 }
 
 func (Multipart) Context() commands.CommandContext {
diff --git a/commands/compose/postpone.go b/commands/compose/postpone.go
index 3dd55554..7aba6b18 100644
--- a/commands/compose/postpone.go
+++ b/commands/compose/postpone.go
@@ -14,7 +14,7 @@ import (
 )
 
 type Postpone struct {
-	Folder string `opt:"-t" complete:"CompleteFolder"`
+	Folder string `opt:"-t" complete:"CompleteFolder" desc:"Override the target folder."`
 }
 
 func init() {
diff --git a/commands/compose/send.go b/commands/compose/send.go
index 0d184bcf..73e3e13a 100644
--- a/commands/compose/send.go
+++ b/commands/compose/send.go
@@ -24,11 +24,11 @@ import (
 )
 
 type Send struct {
-	Archive string `opt:"-a" action:"ParseArchive" metavar:"flat|year|month" complete:"CompleteArchive"`
-	CopyTo  string `opt:"-t" complete:"CompleteFolders"`
+	Archive string `opt:"-a" action:"ParseArchive" metavar:"flat|year|month" complete:"CompleteArchive" desc:"Archive the message being replied to."`
+	CopyTo  string `opt:"-t" complete:"CompleteFolders" desc:"Override the Copy-To folder."`
 
-	CopyToReplied   bool `opt:"-r"`
-	NoCopyToReplied bool `opt:"-R"`
+	CopyToReplied   bool `opt:"-r" desc:"Save sent message to current folder."`
+	NoCopyToReplied bool `opt:"-R" desc:"Do not save sent message to current folder."`
 }
 
 func init() {
diff --git a/commands/compose/switch.go b/commands/compose/switch.go
index 4bcfc136..55dc86e2 100644
--- a/commands/compose/switch.go
+++ b/commands/compose/switch.go
@@ -12,9 +12,9 @@ type AccountSwitcher interface {
 }
 
 type SwitchAccount struct {
-	Next    bool   `opt:"-n"`
-	Prev    bool   `opt:"-p"`
-	Account string `opt:"account" required:"false" complete:"CompleteAccount"`
+	Prev    bool   `opt:"-p" desc:"Switch to previous account."`
+	Next    bool   `opt:"-n" desc:"Switch to next account."`
+	Account string `opt:"account" required:"false" complete:"CompleteAccount" desc:"Account name."`
 }
 
 func init() {
diff --git a/commands/ct.go b/commands/ct.go
index be3d4e98..1ac4641b 100644
--- a/commands/ct.go
+++ b/commands/ct.go
@@ -9,7 +9,7 @@ import (
 )
 
 type ChangeTab struct {
-	Tab string `opt:"tab" complete:"CompleteTab"`
+	Tab string `opt:"tab" complete:"CompleteTab" desc:"Tab name."`
 }
 
 func init() {
diff --git a/commands/eml.go b/commands/eml.go
index d4323a29..91d881fd 100644
--- a/commands/eml.go
+++ b/commands/eml.go
@@ -12,7 +12,7 @@ import (
 )
 
 type Eml struct {
-	Path string `opt:"path" required:"false" complete:"CompletePath"`
+	Path string `opt:"path" required:"false" complete:"CompletePath" desc:"EML file path."`
 }
 
 func init() {
diff --git a/commands/help.go b/commands/help.go
index dab0af1a..30688c5a 100644
--- a/commands/help.go
+++ b/commands/help.go
@@ -7,7 +7,7 @@ import (
 )
 
 type Help struct {
-	Topic string `opt:"topic" action:"ParseTopic" default:"aerc" complete:"CompleteTopic"`
+	Topic string `opt:"topic" action:"ParseTopic" default:"aerc" complete:"CompleteTopic" desc:"Help topic."`
 }
 
 var pages = []string{
diff --git a/commands/menu.go b/commands/menu.go
index 4db1a1d7..4908a2a2 100644
--- a/commands/menu.go
+++ b/commands/menu.go
@@ -16,12 +16,12 @@ import (
 )
 
 type Menu struct {
-	ErrExit     bool   `opt:"-e"`
-	Background  bool   `opt:"-b"`
-	Accounts    bool   `opt:"-a"`
-	Directories bool   `opt:"-d"`
-	Command     string `opt:"-c"`
-	Xargs       string `opt:"..." complete:"CompleteXargs"`
+	ErrExit     bool   `opt:"-e" desc:"Stop executing commands on the first error."`
+	Background  bool   `opt:"-b" desc:"Do NOT spawn the popover dialog."`
+	Accounts    bool   `opt:"-a" desc:"Feed command with account names."`
+	Directories bool   `opt:"-d" desc:"Feed command with folder names."`
+	Command     string `opt:"-c" desc:"Override [general].default-menu-cmd."`
+	Xargs       string `opt:"..." complete:"CompleteXargs" desc:"Command name."`
 }
 
 func init() {
diff --git a/commands/msg/archive.go b/commands/msg/archive.go
index 0b4b8258..eb143b34 100644
--- a/commands/msg/archive.go
+++ b/commands/msg/archive.go
@@ -22,8 +22,8 @@ const (
 var ARCHIVE_TYPES = []string{ARCHIVE_FLAT, ARCHIVE_YEAR, ARCHIVE_MONTH}
 
 type Archive struct {
-	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS"`
-	Type              string                   `opt:"type" action:"ParseArchiveType" metavar:"flat|year|month" complete:"CompleteType"`
+	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS" desc:"Multi-file strategy."`
+	Type              string                   `opt:"type" action:"ParseArchiveType" metavar:"flat|year|month" complete:"CompleteType" desc:"Archiving scheme."`
 }
 
 func (a *Archive) ParseMFS(arg string) error {
diff --git a/commands/msg/bounce.go b/commands/msg/bounce.go
index 0c0452b4..819595cc 100644
--- a/commands/msg/bounce.go
+++ b/commands/msg/bounce.go
@@ -19,8 +19,8 @@ import (
 )
 
 type Bounce struct {
-	Account string   `opt:"-A" complete:"CompleteAccount"`
-	To      []string `opt:"..." required:"true" complete:"CompleteTo"`
+	Account string   `opt:"-A" complete:"CompleteAccount" desc:"Account from which to re-send the message."`
+	To      []string `opt:"..." required:"true" complete:"CompleteTo" desc:"Recipient from address book."`
 }
 
 func init() {
diff --git a/commands/msg/copy.go b/commands/msg/copy.go
index 126dbd8e..ffc6a34f 100644
--- a/commands/msg/copy.go
+++ b/commands/msg/copy.go
@@ -17,11 +17,11 @@ import (
 )
 
 type Copy struct {
-	CreateFolders     bool                     `opt:"-p"`
-	Decrypt           bool                     `opt:"-d"`
-	Account           string                   `opt:"-a" complete:"CompleteAccount"`
-	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS"`
-	Folder            string                   `opt:"folder" complete:"CompleteFolder"`
+	CreateFolders     bool                     `opt:"-p" desc:"Create folder if it does not exist."`
+	Decrypt           bool                     `opt:"-d" desc:"Decrypt the message before copying."`
+	Account           string                   `opt:"-a" complete:"CompleteAccount" desc:"Copy to the specified account."`
+	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS" desc:"Multi-file strategy."`
+	Folder            string                   `opt:"folder" complete:"CompleteFolder" desc:"Target folder."`
 }
 
 func init() {
diff --git a/commands/msg/delete.go b/commands/msg/delete.go
index 4999045e..dcfc5ea1 100644
--- a/commands/msg/delete.go
+++ b/commands/msg/delete.go
@@ -14,7 +14,7 @@ import (
 )
 
 type Delete struct {
-	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS"`
+	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS" desc:"Multi-file strategy."`
 }
 
 func init() {
diff --git a/commands/msg/envelope.go b/commands/msg/envelope.go
index 09e7fa19..d064e43c 100644
--- a/commands/msg/envelope.go
+++ b/commands/msg/envelope.go
@@ -14,8 +14,8 @@ import (
 )
 
 type Envelope struct {
-	Header bool   `opt:"-h"`
-	Format string `opt:"-s" default:"%-20.20s: %s"`
+	Header bool   `opt:"-h" desc:"Show all header fields."`
+	Format string `opt:"-s" default:"%-20.20s: %s" desc:"Format specifier."`
 }
 
 func init() {
diff --git a/commands/msg/fold.go b/commands/msg/fold.go
index d3ec2438..5f2b4b09 100644
--- a/commands/msg/fold.go
+++ b/commands/msg/fold.go
@@ -8,8 +8,8 @@ import (
 )
 
 type Fold struct {
-	All    bool `opt:"-a"`
-	Toggle bool `opt:"-t"`
+	All    bool `opt:"-a" desc:"Fold/unfold all threads."`
+	Toggle bool `opt:"-t" desc:"Toggle between folded/unfolded."`
 }
 
 func init() {
diff --git a/commands/msg/forward.go b/commands/msg/forward.go
index 3bfad8cf..9b6e174b 100644
--- a/commands/msg/forward.go
+++ b/commands/msg/forward.go
@@ -25,12 +25,12 @@ import (
 )
 
 type forward struct {
-	AttachAll  bool     `opt:"-A"`
-	AttachFull bool     `opt:"-F"`
-	Edit       bool     `opt:"-e"`
-	NoEdit     bool     `opt:"-E"`
-	Template   string   `opt:"-T" complete:"CompleteTemplate"`
-	To         []string `opt:"..." required:"false" complete:"CompleteTo"`
+	AttachAll  bool     `opt:"-A" desc:"Forward the message and all attachments."`
+	AttachFull bool     `opt:"-F" desc:"Forward the full message as an RFC 2822 attachment."`
+	Edit       bool     `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit     bool     `opt:"-E" desc:"Force [compose].edit-headers = false."`
+	Template   string   `opt:"-T" complete:"CompleteTemplate" desc:"Template name."`
+	To         []string `opt:"..." required:"false" complete:"CompleteTo" desc:"Recipient from address book."`
 }
 
 func init() {
diff --git a/commands/msg/invite.go b/commands/msg/invite.go
index d9c16263..36add098 100644
--- a/commands/msg/invite.go
+++ b/commands/msg/invite.go
@@ -18,9 +18,9 @@ import (
 )
 
 type invite struct {
-	Edit       bool `opt:"-e"`
-	NoEdit     bool `opt:"-E"`
-	SkipEditor bool `opt:"-s"`
+	Edit       bool `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit     bool `opt:"-E" desc:"Force [compose].edit-headers = false."`
+	SkipEditor bool `opt:"-s" desc:"Skip the editor and go directly to the review screen."`
 }
 
 func init() {
diff --git a/commands/msg/mark.go b/commands/msg/mark.go
index 6c36dcd7..21ba2fc1 100644
--- a/commands/msg/mark.go
+++ b/commands/msg/mark.go
@@ -8,11 +8,11 @@ import (
 )
 
 type Mark struct {
-	All         bool `opt:"-a" aliases:"mark,unmark"`
-	Toggle      bool `opt:"-t" aliases:"mark,unmark"`
-	Visual      bool `opt:"-v" aliases:"mark,unmark"`
-	VisualClear bool `opt:"-V" aliases:"mark,unmark"`
-	Thread      bool `opt:"-T" aliases:"mark,unmark"`
+	All         bool `opt:"-a" aliases:"mark,unmark" desc:"Mark all messages in current folder."`
+	Toggle      bool `opt:"-t" aliases:"mark,unmark" desc:"Toggle the marked state."`
+	Visual      bool `opt:"-v" aliases:"mark,unmark" desc:"Enter / leave visual mark mode."`
+	VisualClear bool `opt:"-V" aliases:"mark,unmark" desc:"Same as -v but does not clear existing selection."`
+	Thread      bool `opt:"-T" aliases:"mark,unmark" desc:"Mark all messages from the selected thread."`
 }
 
 func init() {
diff --git a/commands/msg/modify-labels.go b/commands/msg/modify-labels.go
index e317440c..f89d84a6 100644
--- a/commands/msg/modify-labels.go
+++ b/commands/msg/modify-labels.go
@@ -9,7 +9,7 @@ import (
 )
 
 type ModifyLabels struct {
-	Labels []string `opt:"..." metavar:"[+-]<label>" complete:"CompleteLabels"`
+	Labels []string `opt:"..." metavar:"[+-]<label>" complete:"CompleteLabels" desc:"Message label."`
 }
 
 func init() {
diff --git a/commands/msg/move.go b/commands/msg/move.go
index 63473b13..80f13a22 100644
--- a/commands/msg/move.go
+++ b/commands/msg/move.go
@@ -17,10 +17,10 @@ import (
 )
 
 type Move struct {
-	CreateFolders     bool                     `opt:"-p"`
-	Account           string                   `opt:"-a" complete:"CompleteAccount"`
-	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS"`
-	Folder            string                   `opt:"folder" complete:"CompleteFolder"`
+	CreateFolders     bool                     `opt:"-p" desc:"Create missing folders if required."`
+	Account           string                   `opt:"-a" complete:"CompleteAccount" desc:"Move to specified account."`
+	MultiFileStrategy *types.MultiFileStrategy `opt:"-m" action:"ParseMFS" complete:"CompleteMFS" desc:"Multi-file strategy."`
+	Folder            string                   `opt:"folder" complete:"CompleteFolder" desc:"Target folder."`
 }
 
 func init() {
diff --git a/commands/msg/pipe.go b/commands/msg/pipe.go
index f66e7dca..7a630b55 100644
--- a/commands/msg/pipe.go
+++ b/commands/msg/pipe.go
@@ -21,11 +21,11 @@ import (
 )
 
 type Pipe struct {
-	Background bool   `opt:"-b"`
-	Silent     bool   `opt:"-s"`
-	Full       bool   `opt:"-m"`
-	Decrypt    bool   `opt:"-d"`
-	Part       bool   `opt:"-p"`
+	Background bool   `opt:"-b" desc:"Run the command in the background."`
+	Silent     bool   `opt:"-s" desc:"Silently close the terminal tab after the command exits."`
+	Full       bool   `opt:"-m" desc:"Pipe the full message."`
+	Decrypt    bool   `opt:"-d" desc:"Decrypt the full message before piping."`
+	Part       bool   `opt:"-p" desc:"Only pipe the selected message part."`
 	Command    string `opt:"..."`
 }
 
diff --git a/commands/msg/read.go b/commands/msg/read.go
index e548c12b..3c048e65 100644
--- a/commands/msg/read.go
+++ b/commands/msg/read.go
@@ -12,10 +12,10 @@ import (
 )
 
 type FlagMsg struct {
-	Toggle    bool         `opt:"-t"`
-	Answered  bool         `opt:"-a" aliases:"flag,unflag"`
-	Forwarded bool         `opt:"-f" aliases:"flag,unflag"`
-	Flag      models.Flags `opt:"-x" aliases:"flag,unflag" action:"ParseFlag" complete:"CompleteFlag"`
+	Toggle    bool         `opt:"-t" desc:"Toggle between set and unset."`
+	Answered  bool         `opt:"-a" aliases:"flag,unflag" desc:"Set/unset the answered flag."`
+	Forwarded bool         `opt:"-f" aliases:"flag,unflag" desc:"Set/unset the forwarded flag."`
+	Flag      models.Flags `opt:"-x" aliases:"flag,unflag" action:"ParseFlag" complete:"CompleteFlag" desc:"Flag name."`
 	FlagName  string
 }
 
diff --git a/commands/msg/recall.go b/commands/msg/recall.go
index 5611f289..53a0de34 100644
--- a/commands/msg/recall.go
+++ b/commands/msg/recall.go
@@ -20,9 +20,9 @@ import (
 )
 
 type Recall struct {
-	Force  bool `opt:"-f"`
-	Edit   bool `opt:"-e"`
-	NoEdit bool `opt:"-E"`
+	Force  bool `opt:"-f" desc:"Force recall if not in postpone directory."`
+	Edit   bool `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool `opt:"-E" desc:"Force [compose].edit-headers = false."`
 }
 
 func init() {
diff --git a/commands/msg/reply.go b/commands/msg/reply.go
index 76f1e088..bfcebfca 100644
--- a/commands/msg/reply.go
+++ b/commands/msg/reply.go
@@ -23,13 +23,13 @@ import (
 )
 
 type reply struct {
-	All      bool   `opt:"-a"`
-	Close    bool   `opt:"-c"`
-	Quote    bool   `opt:"-q"`
-	Template string `opt:"-T" complete:"CompleteTemplate"`
-	Edit     bool   `opt:"-e"`
-	NoEdit   bool   `opt:"-E"`
-	Account  string `opt:"-A" complete:"CompleteAccount"`
+	All      bool   `opt:"-a" desc:"Reply to all recipients."`
+	Close    bool   `opt:"-c" desc:"Close the view tab when replying."`
+	Quote    bool   `opt:"-q" desc:"Alias of -T quoted-reply."`
+	Template string `opt:"-T" complete:"CompleteTemplate" desc:"Template name."`
+	Edit     bool   `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit   bool   `opt:"-E" desc:"Force [compose].edit-headers = false."`
+	Account  string `opt:"-A" complete:"CompleteAccount" desc:"Reply with the specified account."`
 }
 
 func init() {
diff --git a/commands/msg/unsubscribe.go b/commands/msg/unsubscribe.go
index 46b86f30..57299aa8 100644
--- a/commands/msg/unsubscribe.go
+++ b/commands/msg/unsubscribe.go
@@ -19,8 +19,8 @@ import (
 // Unsubscribe helps people unsubscribe from mailing lists by way of the
 // List-Unsubscribe header.
 type Unsubscribe struct {
-	Edit   bool `opt:"-e"`
-	NoEdit bool `opt:"-E"`
+	Edit   bool `opt:"-e" desc:"Force [compose].edit-headers = true."`
+	NoEdit bool `opt:"-E" desc:"Force [compose].edit-headers = false."`
 }
 
 func init() {
diff --git a/commands/msgview/open.go b/commands/msgview/open.go
index 7b23423d..4293b7e4 100644
--- a/commands/msgview/open.go
+++ b/commands/msgview/open.go
@@ -14,7 +14,7 @@ import (
 )
 
 type Open struct {
-	Delete bool   `opt:"-d"`
+	Delete bool   `opt:"-d" desc:"Delete temp file after the opener exits."`
 	Cmd    string `opt:"..." required:"false"`
 }
 
diff --git a/commands/msgview/save.go b/commands/msgview/save.go
index 0310ed0e..349a8233 100644
--- a/commands/msgview/save.go
+++ b/commands/msgview/save.go
@@ -18,11 +18,11 @@ import (
 )
 
 type Save struct {
-	Force          bool   `opt:"-f"`
-	CreateDirs     bool   `opt:"-p"`
-	Attachments    bool   `opt:"-a"`
-	AllAttachments bool   `opt:"-A"`
-	Path           string `opt:"path" required:"false" complete:"CompletePath"`
+	Force          bool   `opt:"-f" desc:"Overwrite destination path."`
+	CreateDirs     bool   `opt:"-p" desc:"Create missing directories."`
+	Attachments    bool   `opt:"-a" desc:"Save all attachments parts."`
+	AllAttachments bool   `opt:"-A" desc:"Save all named parts."`
+	Path           string `opt:"path" required:"false" complete:"CompletePath" desc:"Target file path."`
 }
 
 func init() {
diff --git a/commands/new-account.go b/commands/new-account.go
index 9792d7e1..e0fe3b26 100644
--- a/commands/new-account.go
+++ b/commands/new-account.go
@@ -5,7 +5,7 @@ import (
 )
 
 type NewAccount struct {
-	Temp bool `opt:"-t"`
+	Temp bool `opt:"-t" desc:"Create a temporary account."`
 }
 
 func init() {
diff --git a/commands/patch/apply.go b/commands/patch/apply.go
index 12f5b3f8..31ca6964 100644
--- a/commands/patch/apply.go
+++ b/commands/patch/apply.go
@@ -15,9 +15,9 @@ import (
 )
 
 type Apply struct {
-	Cmd      string `opt:"-c"`
-	Worktree string `opt:"-w"`
-	Tag      string `opt:"tag" required:"true" complete:"CompleteTag"`
+	Cmd      string `opt:"-c" desc:"Apply patches with provided command."`
+	Worktree string `opt:"-w" desc:"Create linked worktree on this <commit-ish>."`
+	Tag      string `opt:"tag" required:"true" complete:"CompleteTag" desc:"Identify patches with tag."`
 }
 
 func init() {
diff --git a/commands/patch/drop.go b/commands/patch/drop.go
index dbb1fb07..89d574f1 100644
--- a/commands/patch/drop.go
+++ b/commands/patch/drop.go
@@ -11,7 +11,7 @@ import (
 )
 
 type Drop struct {
-	Tag string `opt:"tag" complete:"CompleteTag"`
+	Tag string `opt:"tag" complete:"CompleteTag" desc:"Repository patch tag."`
 }
 
 func init() {
diff --git a/commands/patch/find.go b/commands/patch/find.go
index a74f926e..ab5252c4 100644
--- a/commands/patch/find.go
+++ b/commands/patch/find.go
@@ -15,8 +15,8 @@ import (
 )
 
 type Find struct {
-	Filter bool     `opt:"-f"`
-	Commit []string `opt:"..." required:"true" complete:"Complete"`
+	Filter bool     `opt:"-f" desc:"Filter message list instead of search."`
+	Commit []string `opt:"..." required:"true" complete:"Complete" desc:"Search for <commit-ish>."`
 }
 
 func init() {
diff --git a/commands/patch/init.go b/commands/patch/init.go
index b7316ee4..7640f268 100644
--- a/commands/patch/init.go
+++ b/commands/patch/init.go
@@ -10,7 +10,7 @@ import (
 )
 
 type Init struct {
-	Force bool   `opt:"-f"`
+	Force bool   `opt:"-f" desc:"Overwrite any existing project."`
 	Name  string `opt:"name" required:"false"`
 }
 
diff --git a/commands/patch/list.go b/commands/patch/list.go
index a9c68e4d..f4a1e5e9 100644
--- a/commands/patch/list.go
+++ b/commands/patch/list.go
@@ -18,7 +18,7 @@ import (
 )
 
 type List struct {
-	All bool `opt:"-a"`
+	All bool `opt:"-a" desc:"List all projects."`
 }
 
 func init() {
diff --git a/commands/patch/patch.go b/commands/patch/patch.go
index 0e19d888..8e280398 100644
--- a/commands/patch/patch.go
+++ b/commands/patch/patch.go
@@ -23,7 +23,7 @@ func register(cmd commands.Command) {
 }
 
 type Patch struct {
-	SubCmd commands.Command `opt:"command" action:"ParseSub" complete:"CompleteSubNames"`
+	SubCmd commands.Command `opt:"command" action:"ParseSub" complete:"CompleteSubNames" desc:"Sub command."`
 	Args   string           `opt:"..." required:"false" complete:"CompleteSubArgs"`
 }
 
diff --git a/commands/patch/switch.go b/commands/patch/switch.go
index 9eb26ef2..3eea1268 100644
--- a/commands/patch/switch.go
+++ b/commands/patch/switch.go
@@ -11,7 +11,7 @@ import (
 )
 
 type Switch struct {
-	Project string `opt:"project" complete:"Complete"`
+	Project string `opt:"project" complete:"Complete" desc:"Project name."`
 }
 
 func init() {
diff --git a/commands/patch/unlink.go b/commands/patch/unlink.go
index da21c15e..5c47d89f 100644
--- a/commands/patch/unlink.go
+++ b/commands/patch/unlink.go
@@ -11,7 +11,7 @@ import (
 )
 
 type Unlink struct {
-	Tag string `opt:"tag" required:"false" complete:"Complete"`
+	Tag string `opt:"tag" required:"false" complete:"Complete" desc:"Project tag name."`
 }
 
 func init() {
diff --git a/commands/prompt.go b/commands/prompt.go
index dc965dd0..8d87446f 100644
--- a/commands/prompt.go
+++ b/commands/prompt.go
@@ -8,7 +8,7 @@ import (
 
 type Prompt struct {
 	Text string   `opt:"text"`
-	Cmd  []string `opt:"..." complete:"CompleteCommand"`
+	Cmd  []string `opt:"..." complete:"CompleteCommand" desc:"Command name."`
 }
 
 func init() {
diff --git a/commands/quit.go b/commands/quit.go
index 8e828823..9c4fec5c 100644
--- a/commands/quit.go
+++ b/commands/quit.go
@@ -7,7 +7,7 @@ import (
 )
 
 type Quit struct {
-	Force bool `opt:"-f"`
+	Force bool `opt:"-f" desc:"Force quit even if a task is pending."`
 }
 
 func init() {
diff --git a/commands/reload.go b/commands/reload.go
index e09290c1..0d4c489a 100644
--- a/commands/reload.go
+++ b/commands/reload.go
@@ -10,9 +10,9 @@ import (
 )
 
 type Reload struct {
-	Binds bool   `opt:"-B"`
-	Conf  bool   `opt:"-C"`
-	Style string `opt:"-s" complete:"CompleteStyle"`
+	Binds bool   `opt:"-B" desc:"Reload binds.conf."`
+	Conf  bool   `opt:"-C" desc:"Reload aerc.conf."`
+	Style string `opt:"-s" complete:"CompleteStyle" desc:"Reload the specified styleset."`
 }
 
 func init() {
diff --git a/commands/z.go b/commands/z.go
index 493e36ff..8ded252c 100644
--- a/commands/z.go
+++ b/commands/z.go
@@ -10,7 +10,7 @@ import (
 )
 
 type Zoxide struct {
-	Args []string `opt:"..." required:"false" metavar:"<query>..." complete:"CompleteFolder"`
+	Args []string `opt:"..." required:"false" metavar:"<query>..." complete:"CompleteFolder" desc:"Target folder."`
 }
 
 func ZoxideAdd(arg string) error {