himalaya/README.md

258 lines
7 KiB
Markdown
Raw Normal View History

2021-03-10 23:28:27 +00:00
# 📫 Himalaya [![gh-actions](https://github.com/soywod/himalaya/workflows/deployment/badge.svg)](https://github.com/soywod/himalaya/actions?query=workflow%3Adeployment)
2020-12-24 23:36:24 +00:00
2021-01-02 23:49:51 +00:00
Minimalist CLI email client, written in Rust.
*The project is under active development. Do not use in production before the
`v1.0.0` (see the [roadmap](https://github.com/soywod/himalaya/projects/2)).*
2021-01-17 15:03:38 +00:00
![image](https://user-images.githubusercontent.com/10437171/104848096-aee51000-58e3-11eb-8d99-bcfab5ca28ba.png)
## Table of contents
* [Motivation](#motivation)
* [Installation](#installation)
2021-03-10 21:35:06 +00:00
* [Configuration](#configuration)
2021-01-17 15:03:38 +00:00
* [Usage](#usage)
* [List mailboxes](#list-mailboxes)
2021-03-10 21:35:06 +00:00
* [List messages](#list-messages)
* [Search messages](#search-messages)
* [Download attachments](#download-attachments)
* [Read a message](#read-a-message)
* [Write a new message](#write-a-new-message)
* [Reply to a message](#reply-to-a-message)
* [Forward a message](#forward-a-message)
2021-03-31 20:57:58 +00:00
* [Copy a message](#copy-a-message)
* [Move a message](#move-a-message)
* [Delete a message](#delete-a-message)
2021-03-11 16:05:01 +00:00
* [Listen to new messages](#listen-to-new-messages)
2021-04-03 10:02:36 +00:00
* [Interfaces](#interfaces)
* [GUI](#gui)
* [TUI](#tui)
2021-01-17 15:03:38 +00:00
* [License](https://github.com/soywod/himalaya/blob/master/LICENSE)
* [Changelog](https://github.com/soywod/himalaya/blob/master/CHANGELOG.md)
* [Credits](#credits)
## Motivation
2021-03-10 21:35:06 +00:00
Bringing emails to the 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
2021-01-17 15:03:38 +00:00
dealing with sensitive data!
2021-03-10 22:08:31 +00:00
The aim of Himalaya is to extract the email logic into a simple (yet solid) CLI
API that can be used either directly from the terminal or UIs. It gives users
more flexibility.
2021-01-17 15:03:38 +00:00
## Installation
2021-01-02 23:49:51 +00:00
```bash
2021-01-17 15:03:38 +00:00
curl -sSL https://raw.githubusercontent.com/soywod/himalaya/master/install.sh | bash
```
2021-03-11 16:05:01 +00:00
*See the [wiki section](https://github.com/soywod/himalaya/wiki/Installation)
for other installation methods.*
2021-01-17 15:03:38 +00:00
## Configuration
```toml
# ~/.config/himalaya/config.toml
name = "Your full name"
2021-03-10 21:35:06 +00:00
downloads-dir = "/abs/path/to/downloads"
2021-04-03 10:02:36 +00:00
signature = "Regards,"
2021-01-17 15:03:38 +00:00
[gmail]
default = true
2021-03-11 23:07:01 +00:00
email = "your.email@gmail.com"
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
imap-host = "imap.gmail.com"
imap-port = 993
2021-03-11 23:07:01 +00:00
imap-login = "your.email@gmail.com"
2021-03-11 16:05:01 +00:00
imap-passwd-cmd = "pass show gmail"
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
smtp-host = "smtp.gmail.com"
smtp-port = 487
2021-03-11 23:07:01 +00:00
smtp-login = "your.email@gmail.com"
smtp-passwd-cmd = "security find-internet-password -gs gmail -w"
2021-01-17 15:03:38 +00:00
```
2021-03-11 16:05:01 +00:00
*See the [wiki section](https://github.com/soywod/himalaya/wiki/Configuration)
for all the options.*
2021-01-17 15:03:38 +00:00
## Usage
```
2021-04-08 16:42:34 +00:00
himalaya 0.2.3
2021-01-14 23:02:15 +00:00
soywod <clement.douin@posteo.net>
2021-01-02 23:49:51 +00:00
📫 Minimalist CLI email client
USAGE:
2021-04-08 16:42:34 +00:00
himalaya [FLAGS] [OPTIONS] [SUBCOMMAND]
2021-01-02 23:49:51 +00:00
FLAGS:
-h, --help Prints help information
2021-04-08 16:42:34 +00:00
-s, --silent Disables any output
2021-01-02 23:49:51 +00:00
-V, --version Prints version information
2021-01-17 09:03:19 +00:00
OPTIONS:
2021-04-03 10:02:36 +00:00
-a, --account <STRING> Selects a specific account
-m, --mailbox <MAILBOX> Selects a specific mailbox [default: INBOX]
-o, --output <STRING> Defines the output format [default: plain] [possible values: plain, json]
2021-01-17 09:03:19 +00:00
2021-01-02 23:49:51 +00:00
SUBCOMMANDS:
2021-04-03 10:02:36 +00:00
attachments Downloads all message attachments
copy Copy a message to the targetted mailbox
delete Delete a message
flags Handles flags
forward Forwards a message
2021-01-15 11:21:07 +00:00
help Prints this message or the help of the given subcommand(s)
2021-04-03 10:02:36 +00:00
idle Spawns a blocking idle daemon
list Lists all messages
mailboxes Lists all mailboxes
move Move a message to the targetted mailbox
read Reads text bodies of a message
reply Answers to a message
save Saves a raw message
search Lists messages matching the given IMAP query
2021-03-10 21:35:06 +00:00
send Sends a raw message
template Generates a message template
2021-04-03 10:02:36 +00:00
write Writes a new message
2021-01-02 23:49:51 +00:00
```
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
*See the [wiki section](https://github.com/soywod/himalaya/wiki/Usage) for more
information about commands.*
2021-01-17 15:03:38 +00:00
### List mailboxes
2021-03-10 21:35:06 +00:00
![image](https://user-images.githubusercontent.com/10437171/104848169-0e432000-58e4-11eb-8410-05f0404c0d99.png)
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
Shows mailboxes in a basic table.
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### List messages
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
![image](https://user-images.githubusercontent.com/10437171/104848096-aee51000-58e3-11eb-8d99-bcfab5ca28ba.png)
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
Shows messages in a basic table.
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Search messages
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
![image](https://user-images.githubusercontent.com/10437171/110698977-9d86f880-81ee-11eb-8990-0ca89c7d4640.png)
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
Shows filtered messages in a basic table. The query should follow the
[RFC-3501](https://tools.ietf.org/html/rfc3501#section-6.4.4).
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Download attachments
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
![image](https://user-images.githubusercontent.com/10437171/104848278-890c3b00-58e4-11eb-9b5c-48807c04f762.png)
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
Downloads all attachments from a message directly to the
[`downloads-dir`](https://github.com/soywod/himalaya/wiki/Configuration).
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Read a message
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
![image](https://user-images.githubusercontent.com/10437171/110701369-5d754500-81f1-11eb-932f-94c2ca8db068.png)
2021-01-17 15:03:38 +00:00
2021-03-11 16:05:01 +00:00
Shows the text content of a message (`text/plain` if exists, otherwise
`text/html`).
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Write a new message
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
```bash
himalaya write
2021-01-17 15:03:38 +00:00
```
2021-03-11 16:05:01 +00:00
Opens your default editor (from the `$EDITOR` environment variable) to compose
a new message.
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Reply to a message
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
```bash
himalaya reply --all 5123
2021-01-17 15:03:38 +00:00
```
2021-03-11 16:05:01 +00:00
Opens your default editor to reply to a message.
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
### Forward a message
2021-01-17 15:03:38 +00:00
2021-03-10 21:35:06 +00:00
```bash
himalaya forward 5123
2021-01-17 15:03:38 +00:00
```
2021-03-11 16:05:01 +00:00
Opens your default editor to forward a message.
2021-03-31 20:57:58 +00:00
### Copy a message
```bash
himalaya copy 5123 Sent
```
Copies a message to the targetted mailbox.
### Move a message
```bash
himalaya move 5123 Drafts
```
Moves a message to the targetted mailbox.
### Delete a message
```bash
himalaya delete 5123
```
Moves a message.
2021-03-11 16:05:01 +00:00
### Listen to new messages
```bash
himalaya idle
```
Starts a session in idle mode (blocking). When a new message arrives, it runs
2021-03-11 23:07:01 +00:00
the command `notify-cmd` defined in the [config
2021-03-11 16:05:01 +00:00
file](https://github.com/soywod/himalaya/wiki/Configuration).
Here a use case with [`systemd`](https://en.wikipedia.org/wiki/Systemd):
```ini
# ~/.config/systemd/user/himalaya.service
[Unit]
Description=Himalaya new messages notifier
[Service]
ExecStart=/usr/local/bin/himalaya idle
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
```bash
systemctl --user enable himalaya.service
systemctl --user start himalaya.service
```
2021-01-17 15:03:38 +00:00
2021-04-03 10:02:36 +00:00
## Interfaces
### GUI
Not yet, but feel free to contribute ;)
### TUI
- [Vim plugin](https://github.com/soywod/himalaya/tree/master/vim)
2021-04-03 10:02:36 +00:00
2021-01-17 15:03:38 +00:00
## Credits
- [IMAP RFC3501](https://tools.ietf.org/html/rfc3501)
- [Iris](https://github.com/soywod/iris.vim), the himalaya predecessor
2021-03-10 22:08:31 +00:00
- [isync](https://isync.sourceforge.io/), an email synchronizer for offline usage
- [NeoMutt](https://neomutt.org/), an email terminal user interface
- [Alpine](http://alpine.x10host.com/alpine/alpine-info/), an other email terminal user interface
- [mutt-wizard](https://github.com/LukeSmithxyz/mutt-wizard), a tool over NeoMutt and isync
- [rust-imap](https://github.com/jonhoo/rust-imap), a rust IMAP lib