mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-07 02:51:50 +00:00
a919269eb5
The bundled himalaya skill documented folder aliases using a stale
TOML schema (`[accounts.NAME.folder.alias]`, singular) that himalaya
v1.2.0 silently ignores. The TOML parses without error, but the
alias resolver never reads the sub-section — every lookup then falls
through to the canonical folder name.
Source: in `pimalaya/core` (the `email-lib` crate himalaya v1.2.0
depends on, currently v0.27.0), `email/src/folder/config.rs` defines
`FolderConfig { aliases: Option<HashMap<String, String>>, ... }`
(plural, no `#[serde(rename)]`/`alias` aliases, no
`deny_unknown_fields`), and `account/config/mod.rs::get_folder_alias`
returns the input verbatim when no alias is found. So the singular
`alias` key deserializes to nothing and lookups silently fall
through.
On Gmail (where `sent` resolves to `[Gmail]/Sent Mail`, not `Sent`)
this means save-to-Sent fails *after* SMTP delivery already
succeeded, and `himalaya message send` exits non-zero. Any caller
(agent, script, user) that retries on that exit code will re-run
the entire send — including SMTP — producing duplicate emails to
recipients. Silent ignore + caller-level retry is significantly
worse than a config that just doesn't work.
This commit updates SKILL.md and references/configuration.md to the
v1.2.0 `folder.aliases.X` syntax (plural, dotted keys, directly
under the account section), adds a Gmail-specific block with the
`[Gmail]/Sent Mail`-style mapping, and adds notes on the failure
mode so future readers don't hit the same trap. SKILL.md version
bumped 1.0.0 → 1.1.0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
227 lines
5.8 KiB
Markdown
227 lines
5.8 KiB
Markdown
# Himalaya Configuration Reference
|
|
|
|
Configuration file location: `~/.config/himalaya/config.toml`
|
|
|
|
## Minimal IMAP + SMTP Setup
|
|
|
|
```toml
|
|
[accounts.default]
|
|
email = "user@example.com"
|
|
display-name = "Your Name"
|
|
default = true
|
|
|
|
# IMAP backend for reading emails
|
|
backend.type = "imap"
|
|
backend.host = "imap.example.com"
|
|
backend.port = 993
|
|
backend.encryption.type = "tls"
|
|
backend.login = "user@example.com"
|
|
backend.auth.type = "password"
|
|
backend.auth.raw = "your-password"
|
|
|
|
# SMTP backend for sending emails
|
|
message.send.backend.type = "smtp"
|
|
message.send.backend.host = "smtp.example.com"
|
|
message.send.backend.port = 587
|
|
message.send.backend.encryption.type = "start-tls"
|
|
message.send.backend.login = "user@example.com"
|
|
message.send.backend.auth.type = "password"
|
|
message.send.backend.auth.raw = "your-password"
|
|
|
|
# Folder aliases — required whenever server folder names differ
|
|
# from himalaya's canonical names. See "Folder Aliases" below.
|
|
folder.aliases.inbox = "INBOX"
|
|
folder.aliases.sent = "Sent"
|
|
folder.aliases.drafts = "Drafts"
|
|
folder.aliases.trash = "Trash"
|
|
```
|
|
|
|
## Password Options
|
|
|
|
### Raw password (testing only, not recommended)
|
|
|
|
```toml
|
|
backend.auth.raw = "your-password"
|
|
```
|
|
|
|
### Password from command (recommended)
|
|
|
|
```toml
|
|
backend.auth.cmd = "pass show email/imap"
|
|
# backend.auth.cmd = "security find-generic-password -a user@example.com -s imap -w"
|
|
```
|
|
|
|
### System keyring (requires keyring feature)
|
|
|
|
```toml
|
|
backend.auth.keyring = "imap-example"
|
|
```
|
|
|
|
Then run `himalaya account configure <account>` to store the password.
|
|
|
|
## Gmail Configuration
|
|
|
|
```toml
|
|
[accounts.gmail]
|
|
email = "you@gmail.com"
|
|
display-name = "Your Name"
|
|
default = true
|
|
|
|
backend.type = "imap"
|
|
backend.host = "imap.gmail.com"
|
|
backend.port = 993
|
|
backend.encryption.type = "tls"
|
|
backend.login = "you@gmail.com"
|
|
backend.auth.type = "password"
|
|
backend.auth.cmd = "pass show google/app-password"
|
|
|
|
message.send.backend.type = "smtp"
|
|
message.send.backend.host = "smtp.gmail.com"
|
|
message.send.backend.port = 587
|
|
message.send.backend.encryption.type = "start-tls"
|
|
message.send.backend.login = "you@gmail.com"
|
|
message.send.backend.auth.type = "password"
|
|
message.send.backend.auth.cmd = "pass show google/app-password"
|
|
|
|
# Gmail folder mapping. Without these, save-to-Sent fails after
|
|
# SMTP delivery succeeds (Gmail's Sent folder is `[Gmail]/Sent Mail`,
|
|
# not `Sent`), and `himalaya message send` exits non-zero. Any
|
|
# caller that retries on that error will re-run SMTP — duplicate
|
|
# emails to recipients. Always include this block for Gmail.
|
|
folder.aliases.inbox = "INBOX"
|
|
folder.aliases.sent = "[Gmail]/Sent Mail"
|
|
folder.aliases.drafts = "[Gmail]/Drafts"
|
|
folder.aliases.trash = "[Gmail]/Trash"
|
|
```
|
|
|
|
**Note:** Gmail requires an App Password if 2FA is enabled.
|
|
|
|
## iCloud Configuration
|
|
|
|
```toml
|
|
[accounts.icloud]
|
|
email = "you@icloud.com"
|
|
display-name = "Your Name"
|
|
|
|
backend.type = "imap"
|
|
backend.host = "imap.mail.me.com"
|
|
backend.port = 993
|
|
backend.encryption.type = "tls"
|
|
backend.login = "you@icloud.com"
|
|
backend.auth.type = "password"
|
|
backend.auth.cmd = "pass show icloud/app-password"
|
|
|
|
message.send.backend.type = "smtp"
|
|
message.send.backend.host = "smtp.mail.me.com"
|
|
message.send.backend.port = 587
|
|
message.send.backend.encryption.type = "start-tls"
|
|
message.send.backend.login = "you@icloud.com"
|
|
message.send.backend.auth.type = "password"
|
|
message.send.backend.auth.cmd = "pass show icloud/app-password"
|
|
```
|
|
|
|
**Note:** Generate an app-specific password at appleid.apple.com
|
|
|
|
## Folder Aliases
|
|
|
|
Map himalaya's canonical folder names (`inbox`, `sent`, `drafts`,
|
|
`trash`) to whatever the server actually calls them. Use the
|
|
v1.2.0 `folder.aliases.X` syntax (plural, dotted keys, directly
|
|
under `[accounts.NAME]`):
|
|
|
|
```toml
|
|
[accounts.default]
|
|
# ... other account config ...
|
|
|
|
folder.aliases.inbox = "INBOX"
|
|
folder.aliases.sent = "Sent"
|
|
folder.aliases.drafts = "Drafts"
|
|
folder.aliases.trash = "Trash"
|
|
```
|
|
|
|
The equivalent TOML sub-section form also works in v1.2.0:
|
|
|
|
```toml
|
|
[accounts.default.folder.aliases]
|
|
inbox = "INBOX"
|
|
sent = "Sent"
|
|
drafts = "Drafts"
|
|
trash = "Trash"
|
|
```
|
|
|
|
> **Don't use the singular `alias` form.** Pre-v1.2.0 docs showed
|
|
> `[accounts.NAME.folder.alias]` (singular). v1.2.0 silently
|
|
> ignores that sub-section — TOML parses without error, but the
|
|
> alias resolver never reads it. Every lookup then falls through
|
|
> to the canonical name. On Gmail (where `sent` is actually
|
|
> `[Gmail]/Sent Mail`) this means save-to-Sent fails *after* SMTP
|
|
> delivery succeeds, and `himalaya message send` exits non-zero.
|
|
> Any caller (agent, script, user) that retries on that error
|
|
> code will re-run the send — including SMTP — producing duplicate
|
|
> emails to recipients. Always use `folder.aliases.X` (plural).
|
|
|
|
## Multiple Accounts
|
|
|
|
```toml
|
|
[accounts.personal]
|
|
email = "personal@example.com"
|
|
default = true
|
|
# ... backend config ...
|
|
|
|
[accounts.work]
|
|
email = "work@company.com"
|
|
# ... backend config ...
|
|
```
|
|
|
|
Switch accounts with `--account`:
|
|
|
|
```bash
|
|
himalaya --account work envelope list
|
|
```
|
|
|
|
## Notmuch Backend (local mail)
|
|
|
|
```toml
|
|
[accounts.local]
|
|
email = "user@example.com"
|
|
|
|
backend.type = "notmuch"
|
|
backend.db-path = "~/.mail/.notmuch"
|
|
```
|
|
|
|
## OAuth2 Authentication (for providers that support it)
|
|
|
|
```toml
|
|
backend.auth.type = "oauth2"
|
|
backend.auth.client-id = "your-client-id"
|
|
backend.auth.client-secret.cmd = "pass show oauth/client-secret"
|
|
backend.auth.access-token.cmd = "pass show oauth/access-token"
|
|
backend.auth.refresh-token.cmd = "pass show oauth/refresh-token"
|
|
backend.auth.auth-url = "https://provider.com/oauth/authorize"
|
|
backend.auth.token-url = "https://provider.com/oauth/token"
|
|
```
|
|
|
|
## Additional Options
|
|
|
|
### Signature
|
|
|
|
```toml
|
|
[accounts.default]
|
|
signature = "Best regards,\nYour Name"
|
|
signature-delim = "-- \n"
|
|
```
|
|
|
|
### Downloads directory
|
|
|
|
```toml
|
|
[accounts.default]
|
|
downloads-dir = "~/Downloads/himalaya"
|
|
```
|
|
|
|
### Editor for composing
|
|
|
|
Set via environment variable:
|
|
|
|
```bash
|
|
export EDITOR="vim"
|
|
```
|