.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "AERC-BINDS" "5" "2024-07-30"
.PP
.SH NAME
.PP
aerc-binds - key bindings configuration file format for \fBaerc\fR(1)
.PP
.SH SYNOPSIS
.PP
The \fIbinds.\&conf\fR file is used for configuring keybindings used in the aerc
interactive client.\& It is expected to be in your XDG config home plus \fIaerc\fR,
which defaults to \fI~/.\&config/aerc/binds.\&conf\fR.\& If the file does not exist, the
built-in default will be installed.\& An alternate file can be specified via the
\fI--binds-conf\fR command line argument, see \fBaerc\fR(1).\&
.PP
This file is written in the ini format with key bindings defined as:
.PP
.RS 4
\fB<key sequence>\fR = \fI<command>\fR
.PP
.RE
Where \fB<key sequence>\fR is the keystrokes pressed (in order) to invoke this
keybinding, and \fI<command>\fR specifies keystrokes that aerc will simulate when
the keybinding is invoked.\& Generally this is used to execute commands, for
example:
.PP
.RS 4
\fBrq\fR = \fI:reply -q<Enter>\fR
.PP
.RE
Pressing \fBr\fR, then \fBq\fR, will simulate typing in \fI:reply -q<Enter>\fR, and execute
\fB:reply -q\fR accordingly.\& It is also possible to invoke keybindings recursively
in a similar fashion.\&
.PP
You may configure different keybindings for different contexts by writing them
into different \fB[sections]\fR of the ini file.\&
.PP
.SH CONTEXTS
.PP
The available contexts are:
.PP
\fB[messages]\fR
.RS 4
keybindings for the message list
.PP
.RE
\fB[view]\fR
.RS 4
keybindings for the message viewer
.PP
.RE
\fB[view::passthrough]\fR
.RS 4
keybindings for the viewer, when in key passthrough mode
(toggled with \fB:toggle-key-passthrough\fR)
.PP
.RE
\fB[compose]\fR
.RS 4
keybindings for the message composer
.PP
.RE
\fB[compose::editor]\fR
.RS 4
keybindings for the composer, when the editor is focused
.PP
.RE
\fB[compose::review]\fR
.RS 4
keybindings for the composer, when reviewing the email before it'\&s sent
.PP
To customize the description shown on the review screen, add a comment
(" # ") at the end of the keybinding.\&
.PP
Example:
.PP
.RS 4
p = :postpone<Enter> # I'\&ll work on it later
.PP
.RE
.RE
\fB[terminal]\fR
.RS 4
keybindings for terminal tabs
.PP
.RE
You may also configure account specific key bindings for each context:
.PP
\fB[context:account=\fR\fIAccountName\fR\fB]\fR
.RS 4
keybindings for this context and account, where \fIAccountName\fR is a
regular expression that matches the account name you provided in \fIaccounts.\&conf\fR.\&
.PP
.RE
Folder and context-specific bindings can be configured for message lists:
.PP
\fB[messages:folder=\fR\fIFolderName\fR\fB]\fR
.br
\fB[view:folder=\fR\fIFolderName\fR\fB]\fR
.br
\fB[compose:folder=\fR\fIFolderName\fR\fB]\fR
.br
\fB[compose::editor:folder=\fR\fIFolderName\fR\fB]\fR
.br
\fB[compose::review:folder=\fR\fIFolderName\fR\fB]\fR
.RS 4
keybindings under this section will be specific to the folder that
matches the regular expression \fIFolderName\fR.\&
Keybindings from a folder specifier will take precedence over account specifiers
.PP
.RE
Examples:
.PP
.nf
.RS 4
[messages:account=Mailbox]
c = :cf path:mailbox/** and<space>

[compose::editor:account=Mailbox2]

[compose::editor:folder=aerc]
y = :send -t aerc

[messages:folder=Drafts]
<Enter> = :recall<Enter>

[messages:folder=Archive/d+/\&.*]
gi = :cf Inbox<Enter>
\&.\&.\&.
.fi
.RE
.PP
You may also configure global keybindings by placing them at the beginning of
the file, before specifying any context-specific sections.\&
.PP
Parent keybindings can be erased in the context ones by specifying an "empty"
binding:
.PP
.nf
.RS 4
[compose::review]
a = :attach<space>
d = :deatch<space>

[compose::review:account=no-attachments]
a =
d =
.fi
.RE
.PP
.SH SPECIAL OPTIONS
.PP
In addition of user defined key sequences, the following special options are
available in each binding context:
.PP
\fB$noinherit\fR = \fItrue\fR|\fIfalse\fR
.RS 4
If set to \fItrue\fR, global keybindings will not be effective in this context.\&
.PP
Default: \fIfalse\fR
.PP
.RE
\fB$ex\fR = \fI<key-stroke>\fR
.RS 4
This can be set to a keystroke which will bring up the command input in this
context.\&
.PP
Default: \fI:\fR
.PP
.RE
\fB$complete\fR = \fI<key-stroke>\fR
.RS 4
This can be set to a keystroke which will trigger command completion in
this context for text inputs that support it.\&
.PP
Default: \fI<tab>\fR
.PP
Note: automatic command completion is disabled when simulating
keystrokes and re-enabled at the end.\& When \fB[ui].\&completion-min-chars\fR
is set to \fImanual\fR (see \fBaerc-config\fR(5)), it is possible to end
a keybinding with the completion key to explicitly display the
completion menu.\& E.\&g.\&:
.PP
.RS 4
\fBo\fR = \fI:cf<space><tab>\fR
.PP
.RE
.RE
.SH SUPPORTED KEYS
.PP
In addition to letters and some characters (e.\&g.\& \fBa\fR, \fBRR\fR, \fBgu\fR, \fB?\&\fR, \fB!\&\fR,
etc.\&), special keys may be specified in \fB<angle brackets>\fR.\& The syntax for
modified or special keys is:
.PP
.RS 4
<C-A-S-key>
.PP
.RE
Where C is control, A is alt, S is shift, and key is the named key or character.\&
.PP
Valid key names are:
.PP
.TS
allbox;l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c
l c.
T{
\fBName\fR
T}	T{
\fBDescription\fR
T}
T{
\fB<space>\fR
T}	T{
" "
T}
T{
\fB<semicolon>\fR
T}	T{
;
T}
T{
\fB<tab>\fR
T}	T{
Tab
T}
T{
\fB<enter>\fR
T}	T{
Enter
T}
T{
\fB<up>\fR
T}	T{
Up arrow
T}
T{
\fB<down>\fR
T}	T{
Down arrow
T}
T{
\fB<right>\fR
T}	T{
Right arrow
T}
T{
\fB<left>\fR
T}	T{
Left arrow
T}
T{
\fB<pgup>\fR
T}	T{
Page Up
T}
T{
\fB<pgdn>\fR
T}	T{
Page Down
T}
T{
\fB<home>\fR
T}	T{
Home
T}
T{
\fB<end>\fR
T}	T{
End
T}
T{
\fB<insert>\fR
T}	T{
Insert
T}
T{
\fB<delete>\fR
T}	T{
Delete
T}
T{
\fB<backspace>\fR
T}	T{
Backspace
T}
T{
\fB<exit>\fR
T}	T{
Exit
T}
T{
\fB<cancel>\fR
T}	T{
Cancel
T}
T{
\fB<print>\fR
T}	T{
Print screen
T}
T{
\fB<pause>\fR
T}	T{
Pause
T}
T{
\fB<backtab>\fR
T}	T{
Shift+Tab
T}
T{
\fB<esc>\fR
T}	T{
Escape
T}
.TE
.sp 1
.SH SEE ALSO
.PP
\fBaerc\fR(1) \fBaerc-config\fR(5)
.PP
.SH AUTHORS
.PP
Originally created by Drew DeVault and maintained by Robin Jarry who is assisted
by other open source contributors.\& For more information about aerc development,
see \fIhttps://sr.\&ht/~rjarry/aerc/\fR.\&