improve readme

This commit is contained in:
Clément DOUIN 2021-01-17 16:03:38 +01:00
parent 65a3851dca
commit 308b74284f
No known key found for this signature in database
GPG key ID: 69C9B9CFFDEE2DEF
3 changed files with 314 additions and 2 deletions

View file

@ -1,4 +1,4 @@
Copyright © 2020 Clément DOUIN (AKA soywod) <clement.douin@posteo.net> Copyright © 2020,2021 Clément DOUIN (AKA soywod) <clement.douin@posteo.net>
All rights reserved. All rights reserved.

282
README.md
View file

@ -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. 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 ```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 Himalaya 0.1.0
soywod <clement.douin@posteo.net> soywod <clement.douin@posteo.net>
📫 Minimalist CLI email client 📫 Minimalist CLI email client
@ -28,3 +114,197 @@ SUBCOMMANDS:
search Lists emails matching the given IMAP query search Lists emails matching the given IMAP query
write Writes a new email 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 <STRING> Name of the mailbox [default: INBOX]
-p, --page <INT> Page number [default: 0]
-s, --size <INT> 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] <QUERY>...
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-m, --mailbox <STRING> Name of the mailbox [default: INBOX]
-p, --page <INT> Page number [default: 0]
-s, --size <INT> Page size [default: 10]
ARGS:
<QUERY>... 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] <UID>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-m, --mailbox <STRING> Name of the mailbox [default: INBOX]
ARGS:
<UID> 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] <UID>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-m, --mailbox <STRING> Name of the mailbox [default: INBOX]
-t, --mime-type <STRING> MIME type to use [default: plain] [possible values: plain, html]
ARGS:
<UID> 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] <UID>
FLAGS:
-h, --help Prints help information
-a, --all Including all recipients
-V, --version Prints version information
OPTIONS:
-m, --mailbox <STRING> Name of the mailbox [default: INBOX]
ARGS:
<UID> 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] <UID>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-m, --mailbox <STRING> Name of the mailbox [default: INBOX]
ARGS:
<UID> 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)

32
install.sh Normal file
View file

@ -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!"