From cd3f5ff6a6a225a248ea451fafc7c19b738f4326 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20DOUIN?= Date: Tue, 27 Aug 2024 08:13:39 +0200 Subject: [PATCH] refactor readme --- README.md | 260 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 213 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index e5d67e6..6a92b8b 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,246 @@
Logo

📫 Himalaya

-

CLI to manage emails,
based on email-lib.

+

CLI to manage emails, based on email-lib

- Release + Release Repology Matrix

-
``` $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2 ``` -![screenshot](./screenshot) +![screenshot](./screenshot.jpeg) ## Features -- [Folder (aka mailbox) management](https://pimalaya.org/himalaya/cli/latest/usage/advanced/folder/) -- Envelope [listing](https://pimalaya.org/himalaya/cli/latest/usage/basic/envelope/list.html), [filtering and sorting](https://pimalaya.org/himalaya/cli/latest/usage/advanced/envelope/list.html) -- [Message composition](https://pimalaya.org/himalaya/cli/latest/usage/basic/message/send.html) based on `$EDITOR` -- Message manipulation ([copy](https://pimalaya.org/himalaya/cli/latest/usage/advanced/message/copy.html)/[move](https://pimalaya.org/himalaya/cli/latest/usage/advanced/message/move.html)/[delete](https://pimalaya.org/himalaya/cli/latest/usage/advanced/message/delete.html)) -- [Multi-accounting](https://pimalaya.org/himalaya/cli/latest/configuration/) -- [Account synchronization](https://pimalaya.org/himalaya/cli/latest/usage/basic/account/sync.html) for offline usage -- Support multiple backends: [IMAP](https://pimalaya.org/himalaya/cli/latest/usage/advanced/imap.html), [Maildir](https://pimalaya.org/himalaya/cli/latest/usage/advanced/maildir.html), [Notmuch](https://pimalaya.org/himalaya/cli/latest/usage/advanced/notmuch.html), [SMTP](https://pimalaya.org/himalaya/cli/latest/usage/advanced/smtp.html), [Sendmail](https://pimalaya.org/himalaya/cli/latest/usage/advanced/sendmail.html). -- [PGP](https://pimalaya.org/himalaya/cli/latest/usage/advanced/pgp/) end-to-end encryption -- Generate [man pages](https://pimalaya.org/himalaya/cli/latest/usage/advanced/man.html) -- Generate [completion scripts](https://pimalaya.org/himalaya/cli/latest/usage/advanced/completion.html) for various shells -- [JSON output](https://pimalaya.org/himalaya/cli/latest/usage/advanced/#-o--output) -- …and more! [Get started now](https://pimalaya.org/himalaya/cli/latest/quickstart.html) +- 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**) +- Multi-accounting +- **JSON** output with `--output json` +- Basic backends: + - **IMAP** (requires `imap` feature) + - **Maildir** (requires `maildir` feature) + - **Notmuch** (requires `notmuch` feature) +- Sending backends: + - **SMTP** (requires `smtp` feature) + - **Sendmail** (requires `sendmail` feature) +- PGP encryption: + - via shell commands (requires `pgp-commands` feature) + - via [GPG](https://www.gnupg.org/) 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) -## Installation +*Himalaya CLI is written in [Rust](https://www.rust-lang.org/), and relies on [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to enable or disable functionalities.* - - - - - -
- -Packaging status - - +*Default features can be found in the `features` section of the [`Cargo.toml`](https://github.com/pimalaya/himalaya/blob/master/Cargo.toml#L18).* -```bash -# Arch Linux (official) -$ pacman -S himalaya +## Installation [![Repology](https://img.shields.io/repology/repositories/himalaya)](https://repology.org/project/himalaya/versions) -# Arch Linux (from sources) -$ yay -S himalaya-git +
+ Prebuilt binary -# Homebrew -$ brew install himalaya + Himalaya CLI can be installed with a prebuilt binary: -# Scoop -$ scoop install himalaya + ```bash + # 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 + ``` -# Cargo -$ cargo install himalaya + These commands install the latest binary from the GitHub [releases](https://github.com/pimalaya/himalaya/releases) section. -# Nix -$ nix-env -i himalaya + *Binaries are built with default cargo features. If you want to enable or disable a feature, please use another installation method.* +
-# Fedora/CentOS -$ dnf copr enable atim/himalaya -$ dnf install himalaya -``` +
+ Cargo -*See the [documentation](https://pimalaya.org/himalaya/cli/latest/installation.html) for other installation methods.* + Himalaya CLI can be installed with [cargo](https://doc.rust-lang.org/cargo/): -
+ ```bash + $ 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: + + ```bash + $ cargo install --git https://github.com/pimalaya/himalaya.git himalaya + ``` + + +
+ Arch Linux + + Himalaya CLI can be installed on [Arch Linux](https://archlinux.org/) with either the community repository: + + ```bash + $ pacman -S himalaya + ``` + + or the [user repository](https://aur.archlinux.org/): + + ```bash + $ git clone https://aur.archlinux.org/himalaya-git.git + $ cd himalaya-git + $ makepkg -isc + ``` + + If you use [yay](https://github.com/Jguer/yay), it is even simplier: + + ```bash + $ yay -S himalaya-git + ``` + +
+ +
+ Homebrew + + Himalaya CLI can be installed with [Homebrew](https://brew.sh/): + + ```bash + $ brew install himalaya + ``` + +
+ +
+ Scoop + + Himalaya CLI can be installed with [Scoop](https://scoop.sh/): + + ```bash + $ scoop install himalaya + ``` + +
+ +
+ Fedora Linux/CentOS/RHEL + + Himalaya CLI can be installed on [Fedora Linux](https://fedoraproject.org/)/CentOS/RHEL via [COPR](https://copr.fedorainfracloud.org/coprs/atim/himalaya/) repo: + + ```bash + $ dnf copr enable atim/himalaya + $ dnf install himalaya + ``` + +
+ +
+ Nix + + Himalaya CLI can be installed with [Nix](https://serokell.io/blog/what-is-nix): + + ```bash + $ nix-env -i himalaya + ``` + + You can also use the git repository for a more up-to-date (but less stable) version: + + ```bash + $ 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](https://nixos.wiki/wiki/Flakes) feature enabled: + + ```bash + $ 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](https://doc.rust-lang.org/cargo/getting-started/installation.html)): + + ```bash + $ curl https://sh.rustup.rs -sSf | sh + ``` + + Then, you need to clone the repository and install dependencies: + + ```bash + $ git clone https://github.com/pimalaya/himalaya.git + $ cd himalaya + $ cargo check + ``` + + Now, you can build Himalaya: + + ```bash + $ cargo build --release + ``` + + *Binaries are available under the `target/release` folder.* +
## Configuration -*Please read the [documentation](https://pimalaya.org/himalaya/cli/latest/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`](./config.sample.toml) +- Paste it in a new file `~/.config/himalaya/config.toml` +- Edit, then comment or uncomment the options you want + +## 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=`: 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 configs? + + All the lookup mechanisms use the email address domain as base for the lookup. It is heavily inspired from the Thunderbird [Autoconfiguration](https://udn.realityripple.com/docs/Mozilla/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