gerodp/hermes-productivity-skills / email/emailops
emailops
VerifiedQuery, search, chat with, and compose/draft/send email from a local EmailOps mailbox via emailops-cli.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.6 KB |
SKILL.md
View on GitHub---
name: emailops
description: "Query, search, chat with, and compose/draft/send email from a local EmailOps mailbox via emailops-cli."
version: 1.1.0
author: community
license: MIT
platforms: [macos, linux]
metadata:
hermes:
tags: [Email, AI, Local-First, Privacy, Search, Chat, Compose, Drafts, Send, EmailOps]
homepage: https://github.com/emailops/emailops
related_skills: [himalaya]
prerequisites:
commands: [emailops-cli]
---
# EmailOps CLI
`emailops-cli` is the headless front-end for **EmailOps**, a privacy-first,
AI-native email client. AI runs locally by default (embedded llama.cpp); email
data lives in a local SQLite database. This skill lets the agent read, search,
chat with, and **compose / draft / send** mail without opening the desktop app.
It complements the `himalaya` skill: Himalaya speaks raw IMAP/SMTP, while
emailops-cli adds Gmail/Outlook OAuth accounts plus **local AI** — semantic
chat over your mail, classification, and embeddings.
## The agent contract: always pass `--json`
Every command supports `--json`, which prints exactly **one stable envelope**
to stdout (logs always go to stderr). Parse this single shape regardless of
success or failure — never scrape the human-readable output:
```jsonc
{ "ok": true, "data": { /* result */ }, "error": null } // success
{ "ok": false, "data": null, "error": { "code": "not_found", "params": {}, "message": "" } } // failure
```
Add `--quiet` to suppress the stderr app-log stream when you only want the
envelope.
## Exit codes (branch on these, not on text)
| Code | Meaning | Code | Meaning |
|------|--------------------|------|--------------------|
| 0 | ok | 5 | network / sync |
| 2 | invalid input | 6 | AI |
| 3 | not found | 130 | cancelled |
| 4 | auth | 1 | otherwise |
## Prerequisites
1. `emailops-cli` on `PATH` (`emailops-cli --version` to verify). It is built
from the EmailOps repo with the `cli` cargo feature; symlink the built
binary into `~/.local/bin` if needed.
2. An EmailOps data directory with at least one configured account. Confirm
with `doctor` before anything else.
## When to use
Use whenever the user asks about *their own email*: searching messages, asking
"what did X say about Y?", listing accounts, reading a specific message, or
checking mailbox health. Also use it to **write mail** — save or edit a draft,
review existing drafts, or send a message. Prefer the cheap read paths
(`doctor`, `accounts`, `emails`, `show`, `search`) over `chat` unless the
question genuinely needs the local LLM.
## Core commands
| Command | Purpose | Cost |
|---------|---------|------|
| `emailops-cli doctor --json` | Env readiness: DB, accounts, AI config. **Loads no model.** | cheap |
| `emailops-cli accounts --json` | List configured accounts (id, email, provider). | cheap |
| `emailops-cli emails --json [--limit N] [--mailbox inbox\|sent\|spam\|trash]` | List recent emails. | cheap |
| `emailops-cli show <ID> --json` | Full single email (headers + body). | cheap |
| `emailops-cli search '<query>' --json [--limit N] [--trace]` | Full-text search across an account's mail. | cheap |
| `emailops-cli chat '<question>' --json [--trace]` | Ask the local AI a question against your mail. | loads LLM |
| `emailops-cli stats --json` | Per-account dashboard totals + coverage. | cheap |
| `emailops-cli compose --to … --subject … (--body …\|--body-file …) --json` | Save a draft (default) or `--send` to deliver. | cheap (write) |
| `emailops-cli drafts --json` | List saved drafts, newest-first. | cheap |
| `emailops-cli draft <ID> --json` | Show a single draft (recipients, subject, body, attachments). | cheap |
Scope to an account with `--account <ID|EMAIL>` (defaults to the single
enabled account). When multiple accounts exist, list them first and pass
`--account` explicitly.
## Procedure
1. **Health check first** (read-only, no model load):
```bash
emailops-cli doctor --json
```
Confirm `data.ok == true` and `data.accountsEnabled > 0`. If `aiEnabled`
is false, avoid `chat` and stick to search/read commands.
2. **Resolve the account** when there's more than one:
```bash
emailops-cli accounts --json
```
Use the returned `id` or `email` with `--account`.
3. **Read paths** for lookups (fast, safe even while the desktop app is open):
```bash
emailops-cli search 'invoice from acme' --json --limit 5
emailops-cli show <id> --json
emailops-cli emails --json --mailbox inbox --limit 25
```
4. **AI path** for natural-language questions (loads the local model):
```bash
emailops-cli chat 'what did the landlord say about the lease renewal?' --json
```
Add `--trace` to inspect routing, retrieval, tool calls, and the sources
behind the answer under `data.trace`.
5. **Multi-turn**: carry context across one-shot invocations by passing the
`conversationId` from a previous `chat --json` result:
```bash
emailops-cli chat 'and what date was that?' --json --conversation <conversationId>
```
6. **Parse the envelope**, branch on `ok` / exit code, and answer the user
from `data`. Surface `error.message` on failure.
## Writing mail: compose, drafts, send
`compose` is the single write path. **By default it saves a draft** (and, on
Gmail/Outlook accounts, also pushes it to the provider's Drafts folder — no
extra flag). Add `--send` to deliver immediately instead. Both paths return the
resulting record under `data`.
> **🚫 NEVER send without explicit user confirmation.** Do not run `compose …
> --send` until you have shown the user the **full email about to be sent** —
> the sending account, **every** To/Cc recipient, the subject, the complete
> body, and any attachments — and the user has **explicitly approved that exact
> message**. No exceptions: not for "obvious" replies, not because the user said
> "send it" earlier about a different draft, not to save a round-trip. A vague
> or prior "go ahead" is **not** sufficient — re-confirm after showing the final
> content. When unsure whether you have approval, **save a draft and ask** — you
> never need permission to save a draft, and you always need it to send.
```bash
# Save a draft (default). --to / --cc / --attach are repeatable.
emailops-cli --account <ID|EMAIL> compose \
--to a@x.com --to b@y.com --cc c@z.com \
--subject "Q3 numbers" \
--body "Hi — draft here." \
--attach /abs/path/report.pdf --json
# Long/rich body: read it from a file instead of --body (mutually exclusive).
emailops-cli --account <ID|EMAIL> compose \
--to a@x.com --subject "Notes" --body-file /abs/path/body.txt --json
# Update an existing draft in place rather than creating a new one.
emailops-cli --account <ID|EMAIL> compose --draft <DRAFT_ID> \
--subject "Q3 numbers (rev)" --body "Updated." --to a@x.com --json
# Send now — ONLY after showing the full email and getting explicit approval
# (see "Mandatory send procedure" below). Delivers immediately; irreversible.
emailops-cli --account <ID|EMAIL> compose \
--to a@x.com --subject "Q3 numbers" --body "Final." --send --json
```
Rules and shapes:
- **`--to`, `--cc`, `--attach` are repeatable**; pass the flag once per value.
- **Body is `--body` XOR `--body-file`.** Supplying both is invalid input
(exit 2, no JSON envelope — it's rejected at the argument layer). `--body-file`
reads the body verbatim from the path.
- **Use real line breaks — write bodies like a normal email.** The CLI stores
the body **verbatim and does not interpret escape sequences**, so a plain
`--body "Hi\n\nText"` is stored as the literal characters `\n` and the
recipient sees `\n` in the message. Format the body the way a person would:
greeting on its own line, a blank line between paragraphs, and a blank line
before the sign-off. Two reliable ways to pass **actual** newlines:
- **`--body-file` (preferred for anything multi-line):** write the body to a
file with real newlines, then reference it —
`printf 'Hi there,\n\nFirst paragraph.\n\nThanks,\nGero\n' > /tmp/body.txt`
then `compose … --body-file /tmp/body.txt`.
- **ANSI-C quoting for short inline bodies:** `--body $'Hi there,\n\nText'`
(the `$'…'` form makes the shell expand `\n` into real newlines; ordinary
`"…"` double quotes do **not**).
- **Attachments are path references**, resolved at compose/send time. Use
**absolute paths readable now**; `filename` and `mimeType` are inferred. Each
returned attachment is `{id, draftId, filePath, filename, mimeType}`.
- **`compose` (draft) returns the draft object**: `id`, `accountId`, `status`
("draft"), `subject`, `toAddresses[]`, `ccAddresses[]`, `body`, `attachments[]`,
`providerDraftId` (null on IMAP/local; set once pushed to Gmail/Outlook),
`createdAt`/`updatedAt`. `drafts` returns an array of these (newest-first);
`draft <ID>` returns one.
- **Drafts don't require recipients** (a bare draft with empty `toAddresses` is
saved fine) — but confirm the recipient list before `--send`.
Review drafts:
```bash
emailops-cli --account <ID|EMAIL> drafts --json # newest-first list
emailops-cli --account <ID|EMAIL> draft <DRAFT_ID> --json # one draft, full
```
### Mandatory send procedure (never skip a step)
`--send` is irreversible and there is **no undo**. Every send MUST follow this
order:
1. **Save it as a draft first** (`compose …`, no `--send`) — never build the
send command straight from user text.
2. **Show the user the full outgoing email** by reading it back with
`draft <ID> --json`: the sending account, **all** To/Cc recipients, the
subject, the **entire** body, and the filename of each attachment. Present it
plainly, not just a summary.
3. **Ask for explicit approval of that exact message** and wait for a clear
"yes, send this". If the user asks for any change, edit the draft
(`compose --draft <ID> …`) and repeat from step 2 — approval of an earlier
version does **not** carry over.
4. Only then run `compose --draft <ID> --send --json` (or an equivalent
`--send` with the identical, already-approved fields).
If you cannot show the full message and get a fresh, explicit yes, **do not
send** — leave the draft saved and tell the user it's ready to review.
## Pitfalls
- **Heavy writes need the app closed.** `sync`, `classify`, `embed`, and the
heavy `compose` write paths — **`--send`, and provider draft push on
Gmail/Outlook** — mutate the SQLite DB (and hit the network); run them only
when the EmailOps desktop app is **not** running (WAL contention). A plain
**save-as-draft on an IMAP/local account is safe even while the app is open**
(the draft stays local — `providerDraftId` is null). Read commands are always
safe.
- **Don't scrape pretty output.** Human output is styled (color/tables) only on
an interactive TTY and is not a stable contract. Always `--json`.
- **Logs are on stderr.** Don't merge stderr into stdout when parsing JSON;
use `--quiet` to silence the app-log stream.
- **No model for `doctor`.** It's intentionally cheap — use it as the gate
before any AI command rather than calling `chat` blindly.
- **Never send without explicit user confirmation.** `--send` is irreversible;
always follow the **Mandatory send procedure** above — save a draft, show the
full email (account, all recipients, subject, body, attachments), get a fresh
explicit yes, then send. When in doubt, leave it as a draft.
- **Same commands in the REPL.** Running `emailops-cli` with no subcommand opens
an interactive REPL that exposes these as `/compose`, `/drafts`, and
`/draft <id>`. For the agent, prefer the one-shot subcommands with `--json`.
- **Double-encoded saved files.** When emailops-cli output is written to a file
and ends up double-escaped (the outer JSON has an `"output"` key whose value
is a string containing the inner JSON), unwrap it first:
```bash
cat saved_result.json | jq -r '.output' | jq ...
```
Without `-r .output`, `jq` will try to parse the escaped string as literal
JSON tokens and silently fail or return wrong results.
- **Outlook/Hotmail control characters break `jq`.** Emails from Outlook/Hotmail
providers can inject raw `\r\n` sequences that cause `jq: parse error: Invalid
string: control characters …` errors. Pre-filter before piping to jq:
```bash
cat output.json | sed 's/\\r//g' | jq ...
```
## Verification
```bash
emailops-cli doctor --json # expect ok:true, accountsEnabled > 0, exit 0
emailops-cli accounts --json # expect a non-empty data array
```
If `doctor` returns `ok:true` with at least one enabled account, the skill is
correctly wired and downstream commands can be trusted.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |