# 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

```bash
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](USER-MANUAL.md)** 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`](skills/emcli/SKILL.md)** is an
[Agent Skill](https://agentskills.io) that teaches an agent to read and send mail through `emcli`,
including a binary installer.