mirror of
https://github.com/soywod/himalaya.git
synced 2024-07-19 22:51:13 +00:00
82ce67f572
* Replace echo with printf The echo(1) command varies among sh implementations. Some interpret hyphen command-line options. It would be unusual, but in theory if $PREFIX began with a hyphen or two then this usage of echo might cause an error or unknown behaviour in such implementations. The printf(1) command is consistent across shell implementations. * Leave privilege elevation to the user * Add die function * Break long line
344 lines
9.6 KiB
Markdown
344 lines
9.6 KiB
Markdown
# 📫 Himalaya [](https://github.com/soywod/himalaya/actions?query=workflow%3Adeployment)
|
|
|
|
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/milestone/5)).*
|
|
|
|
|
|
|
|
## Table of contents
|
|
|
|
* [Motivation](#motivation)
|
|
* [Installation](#installation)
|
|
* [Nix](#nix)
|
|
* [Installing using Nix](#installing-using-nix)
|
|
* [Development using Nix](#development-using-nix)
|
|
* [Configuration](#configuration)
|
|
* [Usage](#usage)
|
|
* [List mailboxes](#list-mailboxes)
|
|
* [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)
|
|
* [Copy a message](#copy-a-message)
|
|
* [Move a message](#move-a-message)
|
|
* [Delete a message](#delete-a-message)
|
|
* [Listen to new messages](#listen-to-new-messages)
|
|
* [Completions](#completions)
|
|
* [Interfaces](#interfaces)
|
|
* [GUI](#gui)
|
|
* [TUI](#tui)
|
|
* [License](https://github.com/soywod/himalaya/blob/master/LICENSE)
|
|
* [Changelog](https://github.com/soywod/himalaya/blob/master/CHANGELOG.md)
|
|
* [Sponsoring](#sponsoring)
|
|
* [Credits](#credits)
|
|
|
|
## Motivation
|
|
|
|
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
|
|
dealing with sensitive data!
|
|
|
|
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.
|
|
|
|
## Installation
|
|
|
|
As root, using sudo:
|
|
|
|
```sh
|
|
curl -sSL https://raw.githubusercontent.com/soywod/himalaya/master/install.sh | sudo sh
|
|
```
|
|
|
|
As a regular user:
|
|
|
|
```sh
|
|
curl -sSL https://raw.githubusercontent.com/soywod/himalaya/master/install.sh | PREFIX=~/.local sh
|
|
```
|
|
|
|
Read the Nix section below for a Nix-based installation method. *See the [wiki section](https://github.com/soywod/himalaya/wiki/Installation)
|
|
for other installation methods.*
|
|
|
|
## Nix
|
|
|
|
[Nix](https://serokell.io/blog/what-is-nix) users might find this section relevant.
|
|
|
|
### Installing using Nix
|
|
|
|
If you already have Nix installed (without Flakes), run the following command to install himalaya to your home directory:
|
|
|
|
```bash
|
|
nix-env -if https://github.com/soywod/himalaya/archive/master.tar.gz
|
|
# Or, `nix-env -if .` from within the source tree checkout
|
|
```
|
|
|
|
Alternatively, if you use Nix with [Flakes](https://nixos.wiki/wiki/Flakes), you can directly run himalaya without installing it anywhere:
|
|
|
|
```bash
|
|
nix run github:soywod/himalaya
|
|
# Or, `nix run` from within the source tree checkout
|
|
```
|
|
|
|
### Development using Nix
|
|
|
|
To enter a development shell,
|
|
|
|
```bash
|
|
nix develop
|
|
```
|
|
|
|
From here, you have access to all the development tools (Rust compiler, cargo, rust language server, code formatter, etc.) necessary to hack on himalaya.
|
|
|
|
If you use VSCode, simply open this project folder - and accept the workspace extension recommendations.
|
|
|
|
#### Troubleshooting Nix
|
|
|
|
- See [here](https://github.com/soywod/himalaya/pull/76#discussion_r609710097) if you get the `hash mismatch in fixed-output derivation` error.
|
|
|
|
## Configuration
|
|
|
|
```toml
|
|
# ~/.config/himalaya/config.toml
|
|
|
|
name = "Your full name"
|
|
downloads-dir = "/abs/path/to/downloads"
|
|
signature = "Regards,"
|
|
|
|
[gmail]
|
|
default = true
|
|
email = "your.email@gmail.com"
|
|
|
|
imap-host = "imap.gmail.com"
|
|
imap-port = 993
|
|
imap-login = "your.email@gmail.com"
|
|
imap-passwd-cmd = "pass show gmail"
|
|
|
|
smtp-host = "smtp.gmail.com"
|
|
smtp-port = 487
|
|
smtp-login = "your.email@gmail.com"
|
|
smtp-passwd-cmd = "security find-internet-password -gs gmail -w"
|
|
```
|
|
|
|
*See the [wiki section](https://github.com/soywod/himalaya/wiki/Configuration)
|
|
for all the options.*
|
|
|
|
## Usage
|
|
|
|
```
|
|
himalaya 0.2.6
|
|
soywod <clement.douin@posteo.net>
|
|
📫 Minimalist CLI email client
|
|
|
|
USAGE:
|
|
himalaya [OPTIONS] [SUBCOMMAND]
|
|
|
|
FLAGS:
|
|
-h, --help Prints help information
|
|
-V, --version Prints version information
|
|
|
|
OPTIONS:
|
|
-a, --account <STRING> Selects a specific account
|
|
-l, --log <LEVEL> Defines the logs level [default: info] [possible values: error, warn, info, debug,
|
|
trace]
|
|
-m, --mailbox <MAILBOX> Selects a specific mailbox [default: INBOX]
|
|
-o, --output <FMT> Defines the output format [default: plain] [possible values: plain, json]
|
|
|
|
SUBCOMMANDS:
|
|
attachments Downloads all message attachments
|
|
copy Copy a message to the targetted mailbox
|
|
delete Delete a message
|
|
flags Handles flags
|
|
forward Forwards a message
|
|
help Prints this message or the help of the given subcommand(s)
|
|
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
|
|
send Sends a raw message
|
|
template Generates a message template
|
|
write Writes a new message
|
|
```
|
|
|
|
*See the [wiki section](https://github.com/soywod/himalaya/wiki/Usage) for more
|
|
information about commands.*
|
|
|
|
### List mailboxes
|
|
|
|
|
|
|
|
Shows mailboxes in a basic table.
|
|
|
|
### List messages
|
|
|
|
|
|
|
|
Shows messages in a basic table.
|
|
|
|
### Search messages
|
|
|
|
|
|
|
|
Shows filtered messages in a basic table. The query should follow the
|
|
[RFC-3501](https://tools.ietf.org/html/rfc3501#section-6.4.4).
|
|
|
|
### Download attachments
|
|
|
|
|
|
|
|
Downloads all attachments from a message directly to the
|
|
[`downloads-dir`](https://github.com/soywod/himalaya/wiki/Configuration).
|
|
|
|
### Read a message
|
|
|
|
|
|
|
|
Shows the text content of a message (`text/plain` if exists, otherwise
|
|
`text/html`).
|
|
|
|
### Write a new message
|
|
|
|
```bash
|
|
himalaya write
|
|
```
|
|
|
|
Opens your default editor (from the `$EDITOR` environment variable) to compose
|
|
a new message.
|
|
|
|
### Reply to a message
|
|
|
|
```bash
|
|
himalaya reply --all 5123
|
|
```
|
|
|
|
Opens your default editor to reply to a message.
|
|
|
|
### Forward a message
|
|
|
|
```bash
|
|
himalaya forward 5123
|
|
```
|
|
|
|
Opens your default editor to forward a message.
|
|
|
|
### 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.
|
|
|
|
### Listen to new messages
|
|
|
|
```bash
|
|
himalaya idle
|
|
```
|
|
|
|
Starts a session in idle mode (blocking). When a new message arrives, it runs
|
|
the command `notify-cmd` defined in the [config
|
|
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
|
|
```
|
|
|
|
## Completions
|
|
|
|
```sh
|
|
Generates the completion script for the given shell
|
|
|
|
USAGE:
|
|
himalaya completion <shell>
|
|
|
|
FLAGS:
|
|
-h, --help Prints help information
|
|
-V, --version Prints version information
|
|
|
|
ARGS:
|
|
<shell> [possible values: bash, zsh, fish]
|
|
```
|
|
|
|
The command prints the generated script to the stdout. You will have
|
|
to manually save and source them. For example:
|
|
|
|
```sh
|
|
himalaya completion bash > himalaya-completions.bash
|
|
```
|
|
|
|
```sh
|
|
# ~/.bashrc
|
|
|
|
source himalaya-completions.bash
|
|
```
|
|
|
|
## Interfaces
|
|
|
|
### GUI
|
|
|
|
Not yet, but feel free to contribute ;)
|
|
|
|
### TUI
|
|
|
|
- [Vim plugin](https://github.com/soywod/himalaya/tree/master/vim)
|
|
|
|
## Sponsoring
|
|
|
|
[](https://github.com/sponsors/soywod)
|
|
[](https://www.paypal.com/paypalme/soywod)
|
|
[](https://ko-fi.com/soywod)
|
|
[](https://www.buymeacoffee.com/soywod)
|
|
|
|
## Credits
|
|
|
|
- [IMAP RFC3501](https://tools.ietf.org/html/rfc3501)
|
|
- [Iris](https://github.com/soywod/iris.vim), the himalaya predecessor
|
|
- [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
|