climail: The Email Client for Your Agent

climail is a clanker-friendly command line email client.

• 📬 Read, write & organize emails
• ⚡ Run instantly with npx (no install)
• 🔐 IMAP + SMTP
• 💌 Gmail ready

Built for agents 🤖 (and humans, too!)

It's a minimalist email client that lives in your terminal. Every command hands back clean JSON, so an AI agent can read your inbox as easily as you can. Let me show you what's behind those bullet points.

Features

There isn't much to climail, and that's on purpose. It does a handful of things, and it tries to do each of them in the least surprising way possible.

Just npx

There's nothing to install and no process to keep alive. It's just an npx command that uses IMAP and SMTP under the hood.

npx climail list --unread
npx climail mark 167 read
npx climail archive 167

If you can run npx, you can run climail: on your laptop, on a server, everywhere.

Configure It in a Minute

Run the setup wizard and answer a few questions:

npx climail init

It asks where to save the config: global (~/.config/climail.conf, which lets climail work from any directory, no per-project setup) or local (a climail.conf in the current directory, handy when a project has its own mailbox). Pick global and you're done. We'll look at the file itself further down.

Every Command Speaks JSON

Every data command prints clean JSON to stdout, so there's nothing to scrape and no columns to line up. Ask for your unread mail:

npx climail list --unread

{
  "ok": true,
  "mailbox": "INBOX",
  "total": 2481,
  "returned": 2,
  "messages": [
    {
      "seq": 2480,
      "uid": 166,
      "date": "2026-07-12T09:03:11.000Z",
      "from": "newsletter@somesaas.io",
      "subject": "🚀 10 game-changing tips",
      "unread": true
    },
    {
      "seq": 2481,
      "uid": 167,
      "date": "2026-07-12T09:41:55.000Z",
      "from": "sarah@acme.co",
      "subject": "Export button throws a 500",
      "unread": true
    }
  ]
}

Every message carries a uid, and that little number is the ID you pass to every other command.

It's the same idea as gh or kubectl -o json: a small tool that pipes cleanly into the next thing, whether that next thing is jq or an agent.

Gmail-Ready Out of the Box

Labels, archiving, and stars are the operations you actually perform on a Gmail inbox, so climail speaks them natively. Labeling applies a real Gmail label, archiving drops the Inbox label instead of trashing the message (exactly like the archive button in the web UI), and starring toggles \Flagged.

But if you are not using a Google email, don't worry: any email works, as long as you have the IMAP and SMTP credentials.

Usage

Every interaction follows the same shape:

npx climail ⟪command⟫

Here's the full set of commands. It looks like a lot, but you'll live in five or six of them and reach for the rest when you need them.

Examples

Reading the table is one thing, but the commands click faster when you see them lined up. Here's a full triage session, top to bottom:

npx climail init
npx climail list --unread
npx climail search --from boss@work.com --since 2026-06-01 --unread
npx climail labels --counts
npx climail read 167 --save-attachments ./att
npx climail mark 167 read
npx climail list --mailbox "[Gmail]/All Mail" --unread
npx climail mark 167 read --mailbox "[Gmail]/All Mail"
npx climail label 167 Triaged
npx climail draft-reply 167 --all --body "Thanks, will take a look."
npx climail send --to them@example.com --reply-to 167 --all --body "On it."
npx climail send --to a@b.com --subject "Report" --body "Attached." --attach ./report.pdf
npx climail forward 167 --to colleague@work.com --body "FYI"
npx climail archive 167

Notice that draft-reply and send are two different commands:

• draft-reply writes a proper threaded reply, correct subject and headers, straight into your Drafts folder. Nothing leaves your account.
• send is the one that actually puts mail on the wire, and it only works once you've configured SMTP. Reading your inbox and emailing people on your behalf are two very different levels of trust, so they're two different commands you opt into separately.

Configuration

npx climail init writes the config for you, but it's a plain text file, so you can just as easily write it yourself:

imap.host=imap.gmail.com
imap.port=993
imap.secure=true
imap.username=you@gmail.com
imap.password="app password here"

# Optional: only needed for the `send` command
smtp.host=smtp.gmail.com
smtp.port=465

The IMAP block is all you need to start reading. The SMTP block is optional, and its absence is exactly why send stays locked until you deliberately add it.

Always keep your config file out of version control, since it holds your credentials.

init lets you choose where this file lives. Global puts it at ~/.config/climail.conf, following the XDG convention, so climail works from any directory. Local drops a climail.conf in the current directory, which takes precedence over the global one when you run commands from there, perfect for a project with its own inbox.

If you manage more than one email address, you can also point any command at a specific file with --config (which skips the prompt in init too):

npx climail list --config ~/work/mail.conf --unread

An Email Client for Agents

So that's the tool. I created it to give my agent an easy way of interacting with an inbox.

These days our agents can automate an incredible amount of our daily work. They write code, review pull requests, update documentation, and poke at APIs through a handful of little CLIs. Yet for many of us, email is still one of the last manual parts of the workflow. And that's odd, because email is exactly the kind of tedious, repetitive triage I'd love to hand off.

The problem was never the agent, it was the interface. A full mail client is a GUI, useless to a clanker. A raw IMAP library means the agent has to write code every time it wants to ask a simple question. Neither one lets you hand the agent a command and get back something it can read.

That's the gap climail fills, and it's why the two boring-sounding features up top are actually the important ones: zero-install npx and JSON on stdout aren't just convenient for you at the terminal. They're the exact two things an agent needs to use a tool with no help from anyone.

Once your agent runs npx climail, it learns how to use it just by reading the help text. No MCP server to stand up, no SDK to wire in.

You can say something like:

Go through my unread mail. Label anything from a customer as "Triaged", and for the ones reporting a bug, draft a short reply letting them know we're on it.

And it will just... do it, by chaining the commands you saw above: search to find them, read to understand each one, label to file them, draft-reply to stage the answers, checking the JSON at every step before taking the next.

The Skill

Do you like agent skills? We got you:

npx skills add nicodevs/climail

In Closing

I hope you enjoy climail. If you have any comments or questions, feel free to create an issue. And throw in a star on GitHub, if you want to help!

See you next time.