Heron
FR Download

AI agents

The heron CLI

Use your email from the terminal with the heron command: install, sign in, commands and examples.

On this page

The heron command gives you access to your email from a terminal. It’s designed for agents that work from the command line, but you can use it yourself too. It uses the same sign-in and the same tools as Heron’s MCP server, so exactly the same permissions: per-mailbox levels and send approval included.

Install

The CLI is coming soon to npm as heronmail. It will need Node 20 or later:

npm i -g heronmail

Sign in

heron login     # opens your browser: Heron sign-in, then authorization
heron status    # server in use and session status
heron accounts  # mailboxes shared with agents and their access level

heron login opens a Heron page in your browser: sign in, choose each mailbox’s access and click Allow. The CLI then shows up in your connected agents as “Heron CLI — your machine’s name”.

heron folders --account <id>
heron list --in inbox --unread --limit 20
heron search "from:camille has:attachment after:2026-09-01"
heron read <id>                  # --max-chars N to limit, --html for HTML
heron thread <id> --no-bodies    # the conversation, without bodies
heron attachment <message-id> <attachment-id>
heron contacts camille

Search uses the same syntax as the app: from:, to:, subject:, has:attachment, is:unread, is:flagged, before:, after:, in:, account:. See Search.

Drafts and organizing

heron reply <id> --body "Thanks, noted!"     # creates a reply draft (--all: reply all)
heron draft --account <id> --to camille@example.com --subject "Thursday" --body-file note.txt
heron archive <id> <id> --thread
heron move <id> --to junk          # inbox, archive, junk, trash or a folder
heron mark-read <id>   heron flag <id>
heron snooze <id> --until tomorrow # laterToday, tonight, tomorrow, weekend, nextWeek or an ISO date
heron undo <token>                 # undoes an action (10 minutes)

Message text can come from --body, --body-file or standard input. The mailbox signature is added automatically; --signature NAME picks another one, --signature none adds none.

Send

The mailbox needs the Everything, including sending level.

heron send --draft <draft-id>                 # sends a draft
heron send --draft <draft-id> --at 2026-11-03T09:00:00+01:00   # schedules it
heron pending <action-id>                     # status of a send awaiting approval

With Confirm before sending, the send waits for your approval in Heron: see Approve an agent’s sends.

Useful options

  • --json: JSON output, ideal for agents and scripts.
  • --server URL or the HERON_SERVER variable: server to use (default https://api.heronmailapp.com).
  • heron tools lists every tool; heron call <tool> '<json>' calls any of them.
  • heron skill prints the usage guide for agents.
  • heron --help lists all commands.
  • Exit code 3: action denied by permissions (level too low or access turned off).

Sign out

heron logout

This revokes the CLI’s access and forgets its tokens. They’re stored in the macOS Keychain when available, otherwise in ~/.config/heron/credentials.json, readable only by you.