emcli/README.md

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.