# 4.6. Commands

User actions are represented by `Command` objects that can then be triggered by `alot.ui.UI.apply_command()`. Command-line strings given by the user via the prompt or key bindings can be translated to `Command` objects using `alot.commands.commandfactory()`. Specific actions are defined as subclasses of `Command` and can be registered to a global command pool using the `registerCommand` decorator.

Note

that the return value of `commandfactory()` depends on the current mode the user interface is in. The mode identifier is a string that is uniquely defined by the currently focuses `Buffer`.

Note

The names of the commands available to the user in any given mode do not correspond one-to-one to these subclasses. You can register a Command multiple times under different names, with different forced constructor parameters and so on. See for instance the definition of BufferFocusCommand in ‘commands/globals.py’:

    @registerCommand(MODE, 'bprevious', forced={'offset': -1},
                     help='focus previous buffer')
    @registerCommand(MODE, 'bnext', forced={'offset': +1},
                     help='focus next buffer')
    class BufferFocusCommand(Command):
        def __init__(self, buffer=None, offset=0, **kwargs):
        ...

class alot.commands.Command

  base class for commands

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.CommandParseError

  could not parse commandline string

class alot.commands.CommandArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

  `ArgumentParser` that raises `CommandParseError` instead of printing to sys.stderr

alot.commands.commandfactory(cmdline, mode='global')

  parses cmdline and constructs a `Command`.

  Parameters:

    - cmdline (str) – command line to interpret

    - mode (str) – mode identifier

alot.commands.lookup_command(cmdname, mode)

  returns commandclass, argparser and forced parameters used to construct a command for cmdname when called in mode.

  Parameters:

    - cmdname (str) – name of the command to look up

    - mode (str) – mode identifier

  Return type:

    (`Command`, `ArgumentParser`, dict(str->dict))

alot.commands.lookup_parser(cmdname, mode)

  returns the `CommandArgumentParser` used to construct a command for cmdname when called in mode.

class alot.commands.registerCommand(mode, name, help=None, usage=None, forced=None, arguments=None)

  Decorator used to register a `Command` as handler for command name in mode so that it can be looked up later using `lookup_command()`.

  Consider this example that shows how a `Command` class definition is decorated to register it as handler for ‘save’ in mode ‘thread’ and add boolean and string arguments:

      .. code-block::

  > @registerCommand(‘thread’, ‘save’, arguments=[

  >   ([’–all’], {‘action’: ‘store_true’, ‘help’:’save all’}), ([‘path’], {‘nargs’:’?’, ‘help’:’path to save to’})], help=’save attachment(s)’)

  > class SaveAttachmentCommand(Command):

  >   pass

  Parameters:

    - mode (str) – mode identifier

    - name (str) – command name to register as

    - help (str) – help string summarizing what this command does

    - usage (str) – overides the auto generated usage string

    - forced (dict (str->str)) – keyword parameter used for commands constructor

    - arguments (list of (list of str, dict (str->str)) – list of arguments given as pairs (args, kwargs) accepted by `argparse.ArgumentParser.add_argument()`.

## 4.6.1. Globals

class alot.commands.globals.BufferCloseCommand(buffer=None, force=False, redraw=True, **kwargs)

  close a buffer

  Parameters:

    - buffer (alot.buffers.Buffer) – the buffer to close or None for current

    - force (bool) – force buffer close

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.BufferFocusCommand(buffer=None, index=None, offset=0, **kwargs)

  focus a `Buffer`

  Parameters:

    - buffer (alot.buffers.Buffer) – the buffer to focus or None

    - index (int) – index (in bufferlist) of the buffer to focus.

    - offset (int) – position of the buffer to focus relative to the currently focussed one. This is used only if buffer is set to None

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.CallCommand(command, **kwargs)

  execute python code

  Parameters:

    command (str) – python command string to call

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.ComposeCommand(envelope=None, headers=None, template=None, sender='', tags=None, subject='', to=None, cc=None, bcc=None, attach=None, omit_signature=False, spawn=None, rest=None, encrypt=False, **kwargs)

  compose a new email

  Parameters:

    - envelope (`Envelope`) – use existing envelope

    - headers (dict (str->str)) – forced header values

    - template (str) – name of template to parse into the envelope after creation. This should be the name of a file in your template_dir

    - sender (str) – From-header value

    - tags (list(str)) – Comma-separated list of tags to apply to message

    - subject (str) – Subject-header value

    - to (str) – To-header value

    - cc (str) – Cc-header value

    - bcc (str) – Bcc-header value

    - attach (str) – Path to files to be attached (globable)

    - omit_signature (bool) – do not attach/append signature

    - spawn (bool) – force spawning of editor in a new terminal

    - rest (list(str)) – remaining parameters. These can start with ‘mailto’ in which case it is interpreted as mailto string. Otherwise it will be interpreted as recipients (to) header

    - encrypt (bool) – if the email should be encrypted

  exception ApplyError
  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.ConfirmCommand(msg=None, **kwargs)

  Prompt user to confirm a sequence of commands.

  Parameters:

    msg (List[str]) – Additional message to prompt the user with

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.EditCommand(path, spawn=None, thread=None, **kwargs)

  edit a file

  Parameters:

    - path (str) – path to the file to be edited

    - spawn (bool) – force running edtor in a new terminal

    - thread (bool) – run asynchronously, don’t block alot

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.ExitCommand(_prompt=True, **kwargs)

  Shut down cleanly.

  Parameters:

    _prompt (bool) – For internal use only, used to control prompting to close without sending, and is used by the BufferCloseCommand if settings change after yielding to the UI.

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.ExternalCommand(cmd, stdin=None, shell=False, spawn=False, refocus=True, thread=False, on_success=None, **kwargs)

  run external command

  Parameters:

    - cmd (list or str) – the command to call

    - stdin (file or str) – input to pipe to the process

    - spawn (bool) – run command in a new terminal

    - shell (bool) – let shell interpret command string

    - thread (bool) – run asynchronously, don’t block alot

    - refocus (bool) – refocus calling buffer after cmd termination

    - on_success (callable) – code to execute after command successfully exited

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.FlushCommand(callback=None, silent=False, **kwargs)

  flush write operations or retry until committed

  Parameters:

    callback (callable) – function to call after successful writeout

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.HelpCommand(commandname='', **kwargs)

  display help for a command (use ‘bindings’ to display all keybindings interpreted in current mode)

  Parameters:

    commandname (str) – command to document

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.MoveCommand(movement=None, **kwargs)

  move in widget

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.NamedQueriesCommand(filtfun=<class 'bool'>, **kwargs)

  opens named queries buffer

  Parameters:

    filtfun (callable (str->bool)) – filter to apply to displayed list

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.OpenBufferlistCommand(filtfun=<function OpenBufferlistCommand.<lambda>>, **kwargs)

  open a list of active buffers

  Parameters:

    filtfun (callable (str->bool)) – filter to apply to displayed list

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.PromptCommand(startwith='', **kwargs)

  prompts for commandline and interprets it upon select

  Parameters:

    startwith (str) – initial content of the prompt widget

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.PythonShellCommand

  open an interactive python shell for introspection

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.RefreshCommand

  refresh the current buffer

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.ReloadCommand

  Reload configuration.

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.RemoveQueryCommand(alias, flush=True, **kwargs)

  remove named query string for given alias

  Parameters:

    - alias (str) – name to use for query string

    - flush (bool) – immediately write out to the index

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.RepeatCommand(**kwargs)

  repeat the command executed last time

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.SaveQueryCommand(alias, query=None, flush=True, **kwargs)

  save alias for query string

  Parameters:

    - alias (str) – name to use for query string

    - query (str or None) – query string to save

    - flush (bool) – immediately write out to the index

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.SearchCommand(query, sort=None, **kwargs)

  open a new search buffer. Search obeys the notmuch search.exclude_tags setting.

  Parameters:

    - query (str) – notmuch querystring

    - sort (str) – how to order results. Must be one of ‘oldest_first’, ‘newest_first’, ‘message_id’ or ‘unsorted’.

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.globals.TagListCommand(filtfun=<function TagListCommand.<lambda>>, tags=None, **kwargs)

  opens taglist buffer

  Parameters:

    filtfun (callable (str->bool)) – filter to apply to displayed list

  apply(ui)

    code that gets executed when this command is applied

## 4.6.2. Envelope

class alot.commands.envelope.AttachCommand(path, **kwargs)

  attach files to the mail

  Parameters:

    path (str) – files to attach (globable string)

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.BodyConvertCommand(action=None, cmd=None)
  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.ChangeDisplaymodeCommand(part=None, **kwargs)

  change wich body alternative is shown

  Parameters:

    part – which part to show

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.DetachCommand(files=None, **kwargs)

  remove attachments from current envelope

  Parameters:

    files (str) – attached file glob to remove

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.EditCommand(envelope=None, spawn=None, refocus=True, part=None, **kwargs)

  edit mail

  Parameters:

    - envelope (`Envelope`) – email to edit

    - spawn (bool) – force spawning of editor in a new terminal

    - refocus – m

    - part (str) – which alternative to edit

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.EncryptCommand(action=None, keyids=None, trusted=False, **kwargs)
  Parameters:

    - action (str) – wether to encrypt/unencrypt/toggleencrypt

    - keyid (str) – the id of the key to encrypt

    - trusted (bool) – wether to filter keys and only use trusted ones

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.RefineCommand(key='', **kwargs)

  prompt to change the value of a header

  Parameters:

    key (str) – key of the header to change

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.RemoveHtmlCommand
  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.SaveCommand

  save draft

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.SendCommand(mail=None, envelope=None, **kwargs)

  send mail

  Parameters:

    - mail – email to send

    - envelope (alot.db.envelope.envelope) – envelope to use to construct the outgoing mail. This will be ignored in case the mail parameter is set.

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.SetCommand(key, value, append=False, **kwargs)

  set header value

  Parameters:

    - key (str) – key of the header to change

    - value (str) – new value

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.SignCommand(action=None, keyid=None, **kwargs)

  toggle signing this email

  Parameters:

    - action (str) – whether to sign/unsign/toggle

    - keyid (str) – which key id to use

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.TagCommand(tags='', action='add', **kwargs)

  manipulate message tags

  Parameters:

    - tags (str) – comma separated list of tagstrings to set

    - action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.ToggleHeaderCommand

  toggle display of all headers

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.envelope.UnsetCommand(key, **kwargs)

  remove header field

  Parameters:

    key (str) – key of the header to remove

  async apply(ui)

    code that gets executed when this command is applied

## 4.6.3. Bufferlist

class alot.commands.bufferlist.BufferCloseCommand

  close focussed buffer

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.bufferlist.BufferFocusCommand

  focus selected buffer

  apply(ui)

    code that gets executed when this command is applied

## 4.6.4. Search

class alot.commands.search.MoveFocusCommand(movement=None, **kwargs)
  apply(ui)

    code that gets executed when this command is applied

class alot.commands.search.OpenThreadCommand(thread=None, all_folded=False, **kwargs)

  open thread in a new buffer

  Parameters:

    thread (`Thread`) – thread to open (Uses focussed thread if unset)

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.search.RefineCommand(query=None, sort=None, **kwargs)

  refine the querystring of this buffer

  Parameters:

    query (list of str) – new querystring given as list of strings as returned by argparse

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.search.RefinePromptCommand

  prompt to change this buffers querystring

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.search.SaveQueryCommand(alias, query=None, flush=True, **kwargs)
  Parameters:

    - alias (str) – name to use for query string

    - query (str or None) – query string to save

    - flush (bool) – immediately write out to the index

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.search.TagCommand(tags='', action='add', allmessages=False, flush=True, **kwargs)

  manipulate message tags

  Parameters:

    - tags (str) – comma separated list of tagstrings to set

    - action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’

    - allmessages (bool) – tag all messages in search result

    - flush (bool) – immediately write out to the index

  async apply(ui)

    code that gets executed when this command is applied

## 4.6.5. Taglist

class alot.commands.taglist.TaglistSelectCommand

  search for messages with selected tag

  async apply(ui)

    code that gets executed when this command is applied

## 4.6.6. Namedqueries

class alot.commands.namedqueries.NamedqueriesSelectCommand(filt=None, **kwargs)

  search for messages with selected query

  async apply(ui)

    code that gets executed when this command is applied

## 4.6.7. Thread

class alot.commands.thread.BounceMailCommand(message=None, **kwargs)

  directly re-send selected message

  Parameters:

    message (alot.db.message.Message) – message to bounce (defaults to selected message)

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.ChangeDisplaymodeCommand(query=None, visible=None, raw=None, all_headers=None, indent=None, mimetree=None, mimepart=False, **kwargs)

  fold or unfold messages

  Parameters:

    - query (str) – notmuch query string used to filter messages to affect

    - visible (True, False, 'toggle' or None) – unfold if True, fold if False, ignore if None

    - raw (True, False, 'toggle' or None) – display raw message text

    - all_headers (True, False, 'toggle' or None) – show all headers (only visible if not in raw mode)

    - indent ('+', '-', or int) – message/reply indentation

    - mimetree (True, False, 'toggle' or None) – show the mime tree of the message

  apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.EditNewCommand(message=None, spawn=None, **kwargs)

  edit message in as new

  Parameters:

    - message (alot.db.message.Message) – message to reply to (defaults to selected message)

    - spawn (bool) – force spawning of editor in a new terminal

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.ForwardCommand(message=None, attach=True, spawn=None, **kwargs)

  forward message

  Parameters:

    - message (alot.db.message.Message) – message to forward (defaults to selected message)

    - attach (bool) – attach original mail instead of inline quoting its body

    - spawn (bool) – force spawning of editor in a new terminal

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.MoveFocusCommand(movement=None, **kwargs)
  apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.OpenAttachmentCommand(attachment, **kwargs)

  displays an attachment according to mailcap

  Parameters:

    attachment (`Attachment`) – attachment to open

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.PipeCommand(cmd, all=False, separately=False, background=False, shell=False, notify_stdout=False, format='raw', add_tags=False, noop_msg='no command specified', confirm_msg='', done_msg=None, **kwargs)

  pipe message(s) to stdin of a shellcommand

  Parameters:

    - cmd (str or list of str) – shellcommand to open

    - all (bool) – pipe all, not only selected message

    - separately (bool) – call command once per message

    - background (bool) – do not suspend the interface

    - shell (bool) – let the shell interpret the command

    - notify_stdout (bool) – display command’s stdout as notification message

    - format (str) – what to pipe to the processes stdin. one of: ‘raw’: message content as is, ‘decoded’: message content, decoded quoted printable, ‘id’: message ids, separated by newlines, ‘filepath’: paths to message files on disk

    - add_tags (bool) – add ‘Tags’ header to the message

    - noop_msg (str) – error notification to show if cmd is empty

    - confirm_msg (str) – confirmation question to ask (continues directly if unset)

    - done_msg (str) – notification message to show upon success

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.PrintCommand(all=False, separately=False, raw=False, add_tags=False, **kwargs)

  print message(s)

  Parameters:

    - all (bool) – print all, not only selected messages

    - separately (bool) – call print command once per message

    - raw (bool) – pipe raw message string to print command

    - add_tags (bool) – add ‘Tags’ header to the message

class alot.commands.thread.RemoveCommand(all=False, **kwargs)

  remove message(s) from the index

  Parameters:

    all (bool) – remove all messages from thread, not just selected one

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.ReplyCommand(message=None, all=False, listreply=None, spawn=None, **kwargs)

  reply to message

  Parameters:

    - message (alot.db.message.Message) – message to reply to (defaults to selected message)

    - all (bool) – group reply; copies recipients from Bcc/Cc/To to the reply

    - listreply (bool) – reply to list; autodetect if unset and enabled in config

    - spawn (bool) – force spawning of editor in a new terminal

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.SaveAttachmentCommand(all=False, path=None, **kwargs)

  save attachment(s)

  Parameters:

    - all (bool) – save all, not only selected attachment

    - path (str) – path to write to. if all is set, this must be a directory.

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.TagCommand(tags='', action='add', all=False, flush=True, **kwargs)

  manipulate message tags

  Parameters:

    - tags (str) – comma separated list of tagstrings to set

    - action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’

    - all (bool) – tag all messages in thread

    - flush (bool) – immediately write out to the index

  async apply(ui)

    code that gets executed when this command is applied

class alot.commands.thread.ThreadSelectCommand

  select focussed element: - if it is a message summary, toggle visibility of the message; - if it is an attachment line, open the attachment - if it is a mimepart, toggle visibility of the mimepart

  async apply(ui)

    code that gets executed when this command is applied

alot.commands.thread.determine_sender(mail, action='reply')

  Inspect a given mail to reply/forward/bounce and find the most appropriate account to act from and construct a suitable From-Header to use.

  Parameters:

    - mail (email.message.Message) – the email to inspect

    - action (str) – intended use case: one of “reply”, “forward” or “bounce”