Configuration
Neverest CLI takes its TOML configuration from one of those paths:
$XDG_CONFIG_HOME/neverest/config.toml$HOME/.config/neverest/config.toml$HOME/.neverestrc
There is 2 ways to configure Neverest CLI:
Automatically, using the wizard
You just need to run neverest. You can configure separated files using the -c|--config argument, for example: neverest -c /tmp/config.toml.
Note: actually you can only create new configurations with the wizard. There is an opened issue #42 to edit existing configurations using the wizard.
Manually, by editing the TOML file
The main section of the configuration file is accounts: it contains all the configurations of your accounts.
An account is a backend tuple (left and right) identified by an [arg::name] that needs to be synchronized. The synchronization can be [config]ured by the user.
The file should first contain your global configuration, followed by your accounts configurations. Each account configuration should be located inside a TOML section (table). The table name should be unique, as it is used to identify an account:
[accounts.example1]
# account config
[accounts.example2]
# account config
# …
Account configuration
An account is composed of a left and a right backend configuration.
default
The defaultness of the current account.
When synchronizing, if no account name is explicitly given, this one will be used by default.
[accounts.example]
default = true
folder.filters
Filter folders to synchronize, for both left and right backends.
[accounts.example]
folder.filters = "all" # include all folders (default)
folder.filters.include = ["INBOX", "Sent"]
folder.filters.exclude = ["All Mails"]
envelope.filters
Filter envelopes to synchronize, for both left and right backends.
Only date filters are available for now.
[accounts.example]
envelope.filters.before = "1990-12-31"
envelope.filters.after = "1990-12-31"
left|right.backend
The configuration of the left and/or right backend.
The left backend can be seen as the source, and the right backend the target, except that there is not implicit difference between source and target. Hence left and right are used instead.
Supported backends: imap, maildir and notmuch.
left|right.folder.aliases
Define custom folder aliases.
Aliases are useful when you need to map a left folder with a right one (or vice versa).
[accounts.example]
left.folder.aliases.drafts = "Brouillons"
right.folder.aliases.drafts = "[Gmail]/Drafts"
left|right.folder.permissions
Control whenever left/right backend can create or delete folders.
[accounts.example]
left.folder.permissions.create = true
right.folder.permissions.delete = false
left|right.flag.permissions
Control whenever left/right backend can change flags.
[accounts.example]
left.flag.permissions.update = false
left|right.message.permissions
Control whenever left/right backend can create or delete messages.
[accounts.example]
left.message.permissions.create = true
right.message.permissions.delete = false
Example
Here a complete and documented config.sample.toml that you can actually test yourself with the following commands:
# save the sample config locally
curl https://raw.githubusercontent.com/soywod/neverest/master/config.sample.toml > config.sample.toml
# spawn a testing IMAP/SMTP server using docker
docker run -it --rm -p 3025:3025 -p 3110:3110 -p 3143:3143 -p 3465:3465 -p 3993:3993 -p 3995:3995 -e GREENMAIL_OPTS='-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose' greenmail/standalone:latest
# test the CLI using the sample config
neverest -c ./config.sample.toml sync
[accounts.example]
# The current `example` account will be used by default.
default = true
# Filter folders according to the given rules.
#
# folder.filter.include = ["INBOX", "Sent"]
# folder.filter.exclude = ["All Mails"]
folder.filter = "all"
# Filter envelopes according to the given rules.
#
# envelope.filter.before = "1990-12-31T23:59:60Z"
# envelope.filter.after = "1990-12-31T23:59:60Z"
# The left backend configuration.
#
# In this example, the left side acts as our local cache.
left.backend.type = "maildir"
left.backend.root-dir = "/tmp/example"
# The left backend permissions.
#
# Example of a full permissive backend (default behaviour):
left.folder.permissions.create = true
left.folder.permissions.delete = true
left.flag.permissions.update = true
left.message.permissions.create = true
left.message.permissions.delete = true
# The right backend configuration.
#
# In this example, the right side acts as our remote.
right.backend.type = "imap"
right.backend.host = "localhost"
right.backend.port = 3143
right.backend.login = "example@localhost"
# The right backend password.
#
# right.backend.passwd.cmd = "echo password"
# right.backend.passwd.keyring = "password-keyring-entry"
right.backend.passwd.raw = "password"
# The right backend encryption.
#
# right.backend.encryption = "tls" # or true
# right.backend.encryption = "start-tls"
right.backend.encryption = "none" # or false
# The right backend permissions.
#
# In this example, we set up safe permissions by denying deletions
# remote side.
right.folder.permissions.delete = false
right.message.permissions.delete = false