steve
d023df1b4a
Fixes from testing email search (docs/enhancements-2026-07-07.md): - New `folders` agent command lists the account's mailboxes (name, delimiter, selectable), INBOX first, so agents can discover archived mail outside INBOX. - `search --all-folders` sweeps every selectable mailbox; each hit carries a `folder` field, `skipped_folders` reports mailboxes the server refused, and --limit caps visible results across the sweep. The sweep deliberately skips EnsureFolderBaseline so a read-only search never mutates list --new state. - Empty search results include a generic `data.hint` with next steps. The hint is a fixed constant per mode, so the invisibility invariant holds: absent and policy-filtered mail produce byte-identical envelopes (codified in TestSearchEmptyHintIndistinguishableFromFiltered). - Skill and user docs: document `--text` full-text search as best-effort (server-dependent); recommend --subject-contains/--from. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
emcli
A single command-line program that mediates all email access for an AI agent. The agent never
holds your email password and never talks to the mail server directly — every read and send goes
through emcli, which enforces the limits you configure (read-only/read-write, sender and
recipient whitelists, subject filters). Even with faulty instructions, the agent can't read mail
it isn't permitted to see or send mail to people it isn't permitted to contact.
Getting started
export EMCLI_ADMIN_KEY="$(head -c 32 /dev/urandom | base64)" # you (human) keep this
export EMCLI_KEY="$(head -c 32 /dev/urandom | base64)" # the agent launcher gets ONLY this
emcli init # writes both wrap slots
emcli doctor # confirm connect/auth (agent key is enough)
emcli init needs both keys. Give the agent's orchestrator only EMCLI_KEY; admin commands (account, whitelist, config, audit) require EMCLI_ADMIN_KEY and will refuse to run without it.
Documentation
See the User Manual for full setup, account configuration (including Gmail app passwords), the agent and admin command reference, the JSON output format, and troubleshooting.
For AI agents, skills/emcli is an
Agent Skill that teaches an agent to read and send mail through emcli,
including a binary installer.