beenull/himalaya
1
0
Fork 0
mirror of https://github.com/soywod/himalaya.git synced 2024-11-24 20:10:23 +00:00
Code Issues Projects Releases Packages Wiki Activity
himalaya/README.md
Clément DOUIN 3fa617cf8f
add readme config example for main email providers
2024-08-27 08:56:36 +02:00

17 KiB
Raw Blame History

Logo

📫 Himalaya

CLI to manage emails, based on email-lib

Release Repology Matrix 

$ himalaya envelope list --account posteo --folder Archives.FOSS --page 2

screenshot

Features

  • Multi-accounting
  • Interactive configuration via wizard (requires wizard feature)
  • Mailbox/folder management (create, list, expunge, purge, delete)
  • Envelope listing, filtering and sorting
  • Message composition based on $EDITOR
  • Message manipulation (copy, move, delete)
  • Basic backends:
    • IMAP (requires imap feature)
    • Maildir (requires maildir feature)
    • Notmuch (requires notmuch feature)
  • Default backends:
    • SMTP (requires smtp feature)
    • Sendmail (requires sendmail feature)
  • PGP encryption:
    • via shell commands (requires pgp-commands feature)
    • via GPG bindings (requires pgp-gpg feature)
    • via native implementation (requires pgp-native feature)
  • Global system keyring for managing secrets (requires keyring feature)
  • OAuth 2.0 authorization (requires oauth2 feature)
  • JSON output via --output json

Himalaya CLI is written in Rust, and relies on cargo features to enable or disable functionalities.

Default features can be found in the features section of the Cargo.toml.

Installation

Himalaya CLI can be installed with a prebuilt binary:

# As root:
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sudo sh

# As a regular user:
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

Binaries are built with default cargo features. If you want to enable or disable a feature, please use another installation method.

Cargo

Himalaya CLI can be installed with cargo:

$ cargo install himalaya

# With only IMAP support:
$ cargo install himalaya --no-default-features --features imap

You can also use the git repository for a more up-to-date (but less stable) version:

$ cargo install --git https://github.com/pimalaya/himalaya.git himalaya
Arch Linux

Himalaya CLI can be installed on Arch Linux with either the community repository:

$ pacman -S himalaya

or the user repository:

$ git clone https://aur.archlinux.org/himalaya-git.git
$ cd himalaya-git
$ makepkg -isc

If you use yay, it is even simplier:

$ yay -S himalaya-git
Homebrew

Himalaya CLI can be installed with Homebrew:

$ brew install himalaya
Scoop

Himalaya CLI can be installed with Scoop:

$ scoop install himalaya
Fedora Linux/CentOS/RHEL

Himalaya CLI can be installed on Fedora Linux/CentOS/RHEL via COPR repo:

$ dnf copr enable atim/himalaya
$ dnf install himalaya
Nix

Himalaya CLI can be installed with Nix:

$ nix-env -i himalaya

You can also use the git repository for a more up-to-date (but less stable) version:

$ nix-env -if https://github.com/pimalaya/himalaya/archive/master.tar.gz

# or, from within the source tree checkout
$ nix-env -if .

If you have the Flakes feature enabled:

$ nix profile install himalaya

# or, from within the source tree checkout
$ nix profile install

# you can also run Himalaya directly without installing it:
$ nix run himalaya
Sources

Himalaya CLI can be installed from sources.

First you need to install the Rust development environment (see the rust installation documentation):

$ curl https://sh.rustup.rs -sSf | sh

Then, you need to clone the repository and install dependencies:

$ git clone https://github.com/pimalaya/himalaya.git
$ cd himalaya
$ cargo check

Now, you can build Himalaya:

$ cargo build --release

Binaries are available under the target/release folder.

Configuration

Just run himalaya, the wizard will help you to configure your default account.

You can also manually write your own configuration, from scratch:

  • Copy the content of the documented ./config.sample.toml
  • Paste it in a new file ~/.config/himalaya/config.toml
  • Edit, then comment or uncomment the options you want
Proton Mail (Bridge)

When using Proton Bridge, emails are synchronized locally and exposed via a local IMAP/SMTP server. This implies 2 things:

  • Id order may be reversed or shuffled, but envelopes will still be sorted by date.
  • SSL/TLS needs to be deactivated manually.
  • The password to use is the one generated by Proton Bridge, not the one from your Proton Mail account.
[accounts.proton]
email = "example@proton.me"

backend = "imap"
imap.host = "127.0.0.1"
imap.port = 1143
imap.encryption = false
imap.login = "example@proton.me"
imap.passwd.raw = "<bridge-imap-p@ssw0rd>"

message.send.backend = "smtp"
smtp.host = "127.0.0.1"
smtp.port = 1025
smtp.encryption = false
smtp.login = "example@proton.me"
smtp.passwd.raw = "<bridge-smtp-p@ssw0rd>"

Keeping your password inside the configuration file is good for testing purpose, but it is not safe. You have 2 better alternatives:

  • Save your password in any password manager that can be queried via the CLI:

    imap.passwd.cmd = "pass show proton"

  • Use the global keyring of your system (requires the keyring cargo feature):

    imap.passwd.keyring = "proton-example"

    Running himalaya configure -a proton will ask for your IMAP password, just paste the one generated previously.

Gmail

Google passwords cannot be used directly. There is two ways to authenticate yourself:

Using App Passwords

This option is the simplest and the fastest. First, be sure that:

  • IMAP is enabled
  • Two-step authentication is enabled
  • Less secure app access is enabled

First create a dedicated password for Himalaya.

[accounts.gmail]
email = "example@gmail.com"

folder.alias.inbox = "INBOX"
folder.alias.sent = "[Gmail]/Sent Mail"
folder.alias.drafts = "[Gmail]/Drafts"
folder.alias.trash = "[Gmail]/Trash"

backend = "imap"
imap.host = "imap.gmail.com"
imap.port = 993
imap.login = "example@gmail.com"
imap.passwd.cmd = "pass show gmail"

message.send.backend = "smtp"
smtp.host = "smtp.gmail.com"
smtp.port = 465
smtp.login = "example@gmail.com"
smtp.passwd.cmd = "pass show gmail"

Keeping your password inside the configuration file is good for testing purpose, but it is not safe. You have 2 better alternatives:

  • Save your password in any password manager that can be queried via the CLI:

    imap.passwd.cmd = "pass show gmail"

  • Use the global keyring of your system (requires the keyring cargo feature):

    imap.passwd.keyring = "gmail-example"

    Running himalaya configure -a gmail will ask for your IMAP password, just paste the one generated previously.

Using OAuth 2.0

This option is the most secure but the hardest to configure. It requires the oauth2 and keyring cargo features.

First, you need to get your OAuth 2.0 credentials by following this guide. Once you get your client id and your client secret, you can configure your Himalaya account this way:

[accounts.gmail]
email = "example@gmail.com"

folder.alias.inbox = "INBOX"
folder.alias.sent = "[Gmail]/Sent Mail"
folder.alias.drafts = "[Gmail]/Drafts"
folder.alias.trash = "[Gmail]/Trash"

backend = "imap"
imap.host = "imap.gmail.com"
imap.port = 993
imap.login = "example@gmail.com"
imap.oauth2.client-id = "<imap-client-id>"
imap.oauth2.auth-url = "https://accounts.google.com/o/oauth2/v2/auth"
imap.oauth2.token-url = "https://www.googleapis.com/oauth2/v3/token"
imap.oauth2.pkce = true
imap.oauth2.scope = "https://mail.google.com/"

message.send.backend = "smtp"
smtp.host = "smtp.gmail.com"
smtp.port = 465
smtp.login = "example@gmail.com"
smtp.oauth2.client-id = "<smtp-client-id>"
smtp.oauth2.auth-url = "https://accounts.google.com/o/oauth2/v2/auth"
smtp.oauth2.token-url = "https://www.googleapis.com/oauth2/v3/token"
smtp.oauth2.pkce = true
smtp.oauth2.scope = "https://mail.google.com/"

# If you want your SMTP to share the same client id (and so the same access token)
# as your IMAP config, you can add the following:
#
# imap.oauth2.client-id = "<client-id>"
# imap.oauth2.client-secret.keyring = "gmail-oauth2-client-secret"
# imap.oauth2.access-token.keyring = "gmail-oauth2-access-token"
# imap.oauth2.refresh-token.keyring = "gmail-oauth2-refresh-token"
#
# imap.oauth2.client-id = "<client-id>"
# imap.oauth2.client-secret.keyring = "gmail-oauth2-client-secret"
# imap.oauth2.access-token.keyring = "gmail-oauth2-access-token"
# smtp.oauth2.refresh-token.keyring = "gmail-oauth2-refresh-token"

Running himalaya configure -a gmail will complete your OAuth 2.0 setup and ask for your client secret.

Outlook 
```toml

[accounts.outlook] email = "example@outlook.com"

backend = "imap" imap.host = "outlook.office365.com" imap.port = 993 imap.login = "example@outlook.com" imap.passwd.cmd = "pass show outlook"

message.send.backend = "smtp" smtp.host = "smtp.mail.outlook.com" smtp.port = 587 smtp.encryption = "start-tls" smtp.login = "example@outlook.com" smtp.passwd.cmd = "pass show outlook"


### Using OAuth 2.0

This option is the most secure but the hardest to configure. First, you need to get your OAuth 2.0 credentials by following [this guide](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth). Once you get your client id and your client secret, you can configure your Himalaya account this way:

```toml
[accounts.outlook]
email = "example@outlook.com"

backend = "imap"
imap.host = "outlook.office365.com"
imap.port = 993
imap.login = "example@outlook.com"
imap.oauth2.client-id = "<imap-client-id>"
imap.oauth2.auth-url = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
imap.oauth2.token-url = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
imap.oauth2.pkce = true
imap.oauth2.scope = "https://outlook.office.com/IMAP.AccessAsUser.All"

message.send.backend = "smtp"
smtp.host = "smtp.mail.outlook.com"
smtp.port = 587
smtp.starttls = true
smtp.login = "example@outlook.com"
smtp.oauth2.client-id = "<smtp-client-id>"
smtp.oauth2.auth-url = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
smtp.oauth2.token-url = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
smtp.oauth2.pkce = true
smtp.oauth2.scope = "https://outlook.office.com/SMTP.Send"

# If you want your SMTP to share the same client id (and so the same access token)
# as your IMAP config, you can add the following:
#
# imap.oauth2.client-id = "<client-id>"
# imap.oauth2.client-secret.keyring = "outlook-oauth2-client-secret"
# imap.oauth2.access-token.keyring = "outlook-oauth2-access-token"
# imap.oauth2.refresh-token.keyring = "outlook-oauth2-refresh-token"
#
# imap.oauth2.client-id = "<client-id>"
# imap.oauth2.client-secret.keyring = "outlook-oauth2-client-secret"
# imap.oauth2.access-token.keyring = "outlook-oauth2-access-token"
# smtp.oauth2.refresh-token.keyring = "outlook-oauth2-refresh-token"

Running himalaya configure -a outlook will complete your OAuth 2.0 setup and ask for your client secret.

iCloud Mail

From the iCloud Mail support page:

  • IMAP port = 993.
  • IMAP login = name of your iCloud Mail email address (for example, johnappleseed, not johnappleseed@icloud.com)
  • SMTP port = 587 with STARTTLS
  • SMTP login = full iCloud Mail email address (for example, johnappleseed@icloud.com, not johnappleseed)
[accounts.icloud]
email = "johnappleseed@icloud.com"

backend = "imap"
imap.host = "imap.mail.me.com"
imap.port = 993
imap.login = "johnappleseed"
imap.passwd.cmd = "pass show icloud"

message.send.backend = "smtp"
smtp.host = "smtp.mail.me.com"
smtp.port = 587
smtp.encryption = "start-tls"
smtp.login = "johnappleseed@icloud.com"
smtp.passwd.cmd = "pass show icloud"

FAQ

How to debug Himalaya CLI?

The simplest way is to use --debug and --trace arguments.

The advanced way is based on environment variables:

  • RUST_LOG=<level>: determines the log level filter, can be one of off, error, warn, info, debug and trace.
  • RUST_SPANTRACE=1: enables the spantrace (a span represent periods of time in which a program was executing in a particular context).
  • RUST_BACKTRACE=1: enables the error backtrace.
  • RUST_BACKTRACE=full: enables the full error backtrace, which include source lines where the error originated from.

Logs are written to the stderr, which means that you can redirect them easily to a file:

RUST_LOG=debug himalaya 2>/tmp/himalaya.log
How the wizard discovers IMAP/SMTP configs?

All the lookup mechanisms use the email address domain as base for the lookup. It is heavily inspired from the Thunderbird Autoconfiguration protocol. For example, for the email address test@example.com, the lookup is performed as (in this order):

  1. check for autoconfig.example.com
  2. look up of example.com in the ISPDB (the Thunderbird central database)
  3. look up MX example.com in DNS, and for mx1.mail.hoster.com, look up hoster.com in the ISPDB
  4. look up SRV example.com in DNS
  5. try to guess (imap.example.com, smtp.example.com…)

Sponsoring

nlnet

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from:

If you appreciate the project, feel free to donate using one of the following providers:

GitHub PayPal Ko-fi Buy Me a Coffee Liberapay