# Use with AI agents

AI coding agents such as Claude Code, Cursor or Codex can already run terminal commands, so they can drive fob-email directly. Ask in plain language, for example "download every invoice PDF that arrived this month", and the agent runs the commands, reads the JSON and does the work.

<Video title="Find and file invoices from your inbox with Claude Code and fob-email (3–4 min)" />

## 1. Install and connect

Install the CLI and connect a mailbox yourself first ([install](/docs/email/cli/install), [connect](/docs/email/connect)). If you'd rather the agent do it, tell it to run `fob-email getting-started`. That command checks for an existing account first, and tells agents to ask you for the app password rather than make one up.

<Callout type="warning" title="Decide what the agent may change">
fob-email has no read-only mode: an account that can read can also move, delete and send. Keep your agent's approval prompts on for commands that change mail, and consider a separate mailbox (for example a dedicated `invoices@` address) for agent work.
</Callout>

## 2. Tell the agent about fob-email

Add a short note to your project's agent instructions (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` or similar):

```markdown
## Email

Use the `fob-email` CLI for anything in our mailbox.

- Start with `fob-email config accounts list` to confirm which mailbox is current.
- Discover commands with `fob-email --help` and `fob-email <resource> <action> --help`.
- Use `--json` and parse the output; don't scrape tables.
- Message IDs belong to a folder: always pass the same `--folder` the ID came from.
- Never run `emails delete`, `drafts delete`, `folders delete`, `emails send` or `drafts send` without asking me first.
- Docs (raw Markdown): https://finopsbricks.com/llms.txt
```

## 3. Ask

Some requests that work well:

- "List unread emails from the last week that have attachments, grouped by sender."
- "Download the PDF attachments from every email from billing@vendor.example since September 1st into ./invoices."
- "Move every bank statement email in my inbox to the Statements folder." Review the list before it moves anything.
- "Draft a reply-style email to finance@ summarising the invoices you found." Then send it yourself after reading the draft.

The agent will usually run `emails search … --json`, then `download` or `move` per message. That's expected: fob-email does one thing per command and the agent strings them together.

## Docs for agents

Every docs page is also served as raw Markdown, which is easier for agents to read than HTML:

- Index of all pages: [`/llms.txt`](/llms.txt)
- Any page: add `/md` after `/docs`. For example, this page is at [`/docs/md/email/cli/ai-agents`](/docs/md/email/cli/ai-agents)