From 308b74284ffe1946f5df5005462e5818c8d01850 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20DOUIN?= Date: Sun, 17 Jan 2021 16:03:38 +0100 Subject: [PATCH] improve readme --- LICENSE | 2 +- README.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++++- install.sh | 32 ++++++ 3 files changed, 314 insertions(+), 2 deletions(-) create mode 100644 install.sh diff --git a/LICENSE b/LICENSE index 940b2d7..ad9998a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright © 2020 Clément DOUIN (AKA soywod) +Copyright © 2020,2021 Clément DOUIN (AKA soywod) All rights reserved. diff --git a/README.md b/README.md index 86ec810..036b36f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,94 @@ -# 📫 Himalaya [WIP] +# 📫 Himalaya [![gh-actions](https://github.com/soywod/himalaya/workflows/release/badge.svg)](https://github.com/soywod/himalaya/actions?query=workflow%3Arelease) Minimalist CLI email client, written in Rust. +![image](https://user-images.githubusercontent.com/10437171/104848096-aee51000-58e3-11eb-8d99-bcfab5ca28ba.png) + +## Table of contents + +* [Motivation](#motivation) +* [Installation](#installation) +* [Usage](#usage) + * [List mailboxes](#list-mailboxes) + * [List emails](#list-emails) + * [Search emails](#search-emails) + * [Download email attachments](#download-email-attachments) + * [Read email](#read-email) + * [Reply email](#reply-email) + * [Forward email](#forward-email) +* [License](https://github.com/soywod/himalaya/blob/master/LICENSE) +* [Changelog](https://github.com/soywod/himalaya/blob/master/CHANGELOG.md) +* [Credits](#credits) + +## Motivation + +Bringing emails to your terminal is a pain. The mainstream TUI, (neo)mutt, +takes time to configure. The default mapping is not intuitive when coming from +the Vim environment. It is even scary to use at the beginning, since you are +dealing with sensitive data! + +The aim of Himalaya is to extract the email logic into a simple CLI API that +can be used either directly for the terminal or from various interfaces. It +gives users more flexibility. + +## Installation + ```bash +curl -sSL https://raw.githubusercontent.com/soywod/himalaya/master/install.sh | bash +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Installation) for +more information.* + +## Configuration + +```toml +# ~/.config/himalaya/config.toml + +name = "Your full name" +downloads_dir = "/abs/path/to/downloads" + +# Himalaya supports the multi-account +# Each account should be inside a TOML section +[gmail] +default = true +email = "my.email@gmail.com" + +imap_host = "imap.gmail.com" +imap_port = 993 +imap_login = "p.durant@gmail.test.com" +imap_passwd_cmd = "pass show gmail" + +smtp_host = "smtp.gmail.com" +smtp_port = 487 +smtp_login = "p.durant@gmail.test.com" +smtp_passwd_cmd = "pass show gmail" + +[posteo] +name = "Your overriden full name" +downloads_dir = "/abs/path/to/overriden/downloads" +email = "my.email@posteo.net" + +imap_host = "posteo.de" +imap_port = 993 +imap_login = "my.email@posteo.net" +imap_passwd_cmd = "security find-internet-password -gs posteo -w" + +smtp_host = "posteo.de" +smtp_port = 487 +smtp_login = "my.email@posteo.net" +smtp_passwd_cmd = "security find-internet-password -gs posteo -w" + +# [other account] +# ... +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Configuration) for +more information.* + +## Usage + +``` Himalaya 0.1.0 soywod 📫 Minimalist CLI email client @@ -28,3 +114,197 @@ SUBCOMMANDS: search Lists emails matching the given IMAP query write Writes a new email ``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage) for more +information.* + +### List mailboxes + +![image](https://user-images.githubusercontent.com/10437171/104848169-0e432000-58e4-11eb-8410-05f0404c0d99.png) + +``` +himalaya-mailboxes +Lists all available mailboxes + +USAGE: + himalaya mailboxes + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:mailboxes) +for more information.* + +### List emails + +![image](https://user-images.githubusercontent.com/10437171/104848096-aee51000-58e3-11eb-8d99-bcfab5ca28ba.png) + +``` +himalaya-list +Lists emails sorted by arrival date + +USAGE: + himalaya list [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + -p, --page Page number [default: 0] + -s, --size Page size [default: 10] +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:list) for +more information.* + +### Search emails + +![image](https://user-images.githubusercontent.com/10437171/104848096-aee51000-58e3-11eb-8d99-bcfab5ca28ba.png) + +``` +himalaya-search +Lists emails matching the given IMAP query + +USAGE: + himalaya search [OPTIONS] ... + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + -p, --page Page number [default: 0] + -s, --size Page size [default: 10] + +ARGS: + ... IMAP query (see https://tools.ietf.org/html/rfc3501#section-6.4.4) +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:search) for +more information.* + +### Download email attachments + +![image](https://user-images.githubusercontent.com/10437171/104848278-890c3b00-58e4-11eb-9b5c-48807c04f762.png) + +``` +himalaya-attachments +Downloads all attachments from an email + +USAGE: + himalaya attachments [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + +ARGS: + UID of the email +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:attachments) +for more information.* + +### Read email + +``` +himalaya-read +Reads text bodies of an email + +USAGE: + himalaya read [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + -t, --mime-type MIME type to use [default: plain] [possible values: plain, html] + +ARGS: + UID of the email +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:read) for +more information.* + +### Write email + +``` +himalaya-write +Writes a new email + +USAGE: + himalaya write + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:write) for +more information.* + +### Reply email + +``` +himalaya-reply +Answers to an email + +USAGE: + himalaya reply [FLAGS] [OPTIONS] + +FLAGS: + -h, --help Prints help information + -a, --all Including all recipients + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + +ARGS: + UID of the email +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:reply) for +more information.* + +### Forward email + +``` +himalaya-forward +Forwards an email + +USAGE: + himalaya forward [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -m, --mailbox Name of the mailbox [default: INBOX] + +ARGS: + UID of the email +``` + +*See [wiki section](https://github.com/soywod/himalaya/wiki/Usage:forward) for +more information.* + +## Credits + +- [IMAP RFC3501](https://tools.ietf.org/html/rfc3501) +- [Iris](https://github.com/soywod/iris.vim), the himalaya predecessor +- [Neomutt](https://neomutt.org/) +- [Alpine](http://alpine.x10host.com/alpine/alpine-info/) +- [rust-imap](https://github.com/jonhoo/rust-imap) diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..065cbba --- /dev/null +++ b/install.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +get_os () { + if [[ "$OSTYPE" == "linux-gnu" ]]; then + echo "linux" + elif [[ "$OSTYPE" == "freebsd"* ]]; then + echo "linux" + elif [[ "$OSTYPE" == "darwin"* ]]; then + echo "macos" + elif [[ "$OSTYPE" == "cygwin" ]]; then + echo "windows" + elif [[ "$OSTYPE" == "msys" ]]; then + echo "windows" + elif [[ "$OSTYPE" == "win32" ]]; then + echo "windows" + else + return -1 + fi +} + +OS=`get_os` + +cd /tmp +echo "Downloading latest ${OS} release…" +curl -sLo himalaya.tar.gz "https://github.com/soywod/himalaya/releases/latest/download/himalaya-${OS}.tar.gz" +echo "Installing binary…" +tar -xzf himalaya.tar.gz +rm himalaya.tar.gz +chmod u+x himalaya.exe +sudo mv himalaya.exe /usr/local/bin/himalaya + +echo "$(himalaya --version) installed!"