# 2. Usage

## 2.1. Command-Line Invocation

Synopsis

alot [options …] [subcommand]

Options

`-r, --read-only`

  open notmuch database in read-only mode

`-c FILENAME, --config=FILENAME`

  configuration file (default: ~/.config/alot/config)

`-n FILENAME, --notmuch-config=FILENAME`

  notmuch configuration file (default: see notmuch-config(1))

`-C COLOURS, --colour-mode=COLOURS`

  number of colours to use on the terminal; must be 1, 16 or 256 (default: configuration option colourmode or 256)

`-p PATH, --mailindex-path=PATH`

  path to notmuch index

`-d LEVEL, --debug-level=LEVEL`

  debug level; must be one of debug, info, warning or error (default: info)

`-l FILENAME, --logfile=FILENAME`

  log file (default: /dev/null)

`-h, --help`

  display help and exit

`-v, --version`

  output version information and exit

Commands

alot can be invoked with an optional subcommand from the command line. Those have their own parameters (see e.g. alot search –help). The following commands are available.

search

  start in a search buffer using the query string provided as parameter (see notmuch-search-terms(7))

compose

  compose a new message

bufferlist

  start with only a bufferlist buffer open

taglist

  start with only a taglist buffer open

namedqueries

  start with list of named queries

pyshell

  start the interactive python shell inside alot

## 2.2. UNIX Signals

SIGUSR1

  Refreshes the current buffer.

SIGINT

  Shuts down the user interface.

## 2.3. First Steps in the UI

The arrow keys, page-up/down, j, k and Space can be used to move the focus. Escape cancels prompts and Enter selects. Hit : at any time and type in commands to the prompt.

The interface shows one buffer at a time, you can use Tab and Shift-Tab to switch between them, close the current buffer with d and list them all with ;.

The buffer type or mode (displayed at the bottom left) determines which prompt commands are available. Usage information on any command can be listed by typing help YOURCOMMAND to the prompt. The keybindings for the current mode are listed upon pressing ?.

## 2.4. Commands

Alot interprets user input as command line strings given via its prompt or bound to keys in the config. Command lines are semi-colon separated command strings, each of which starts with a command name and possibly followed by arguments.

See the sections below for which commands are available in which (UI) mode. global commands are available independently of the mode.

Global commands

  globally available commands

Commands in ‘bufferlist’ mode

  commands while listing active buffers

Commands in ‘envelope’ mode

  commands during message composition

Commands in ‘namedqueries’ mode

  commands while listing all named queries from the notmuch database

Commands in ‘search’ mode

  commands available when showing thread search results

Commands in ‘taglist’ mode

  commands while listing all tagstrings present in the notmuch database

Commands in ‘thread’ mode

  commands available while displaying a thread

## 2.5. Cryptography

Alot has built in support for constructing signed and/or encrypted mails according to PGP/MIME (RFC 3156, RFC 3156) via gnupg. It does however rely on a running gpg-agent to handle password entries.

Note

You need to have gpg-agent running to use GPG with alot!

gpg-agent will handle passphrase entry in a secure and configurable way, and it will cache your passphrase for some time so you don’t have to enter it over and over again. For details on how to set this up we refer to gnupg’s manual.

Signing outgoing emails

You can use the commands sign, unsign and togglesign in envelope mode to determine if you want this mail signed and if so, which key to use. To specify the key to use you may pass a hint string as argument to the sign or togglesign command. This hint would typically be a fingerprint or an email address associated (by gnupg) with a key.

Signing (and hence passwd entry) will be done at most once shortly before a mail is sent.

In case no key is specified, alot will leave the selection of a suitable key to gnupg so you can influence that by setting the default-key option in `~/.gnupg/gpg.conf` accordingly.

You can set the default to-sign bit and the key to use for each account individually using the options sign_by_default and gpg_key.

Encrypt outgoing emails

You can use the commands encrypt, unencrypt and and toggleencrypt and in envelope mode to ask alot to encrypt the mail before sending. The encrypt command accepts an optional hint string as argument to determine the key of the recipient.

You can set the default to-encrypt bit for each account individually using the option encrypt_by_default.

Note

If you want to access encrypt mail later it is useful to add yourself to the list of recipients when encrypting with gpg (not the recipients whom mail is actually send to). The simplest way to do this is to use the encrypt-to option in the `~/.gnupg/gpg.conf`. But you might have to specify the correct encryption subkey otherwise gpg seems to throw an error.