Herald

Prerequisites

• An IMAP account and SMTP settings, unless you run demo mode.
• Recommended: a modern terminal with mouse events and OSC 8 hyperlinks for clickable navigation and hardened email links. For inline image rendering, use a Kitty-protocol terminal such as Ghostty on macOS or Kitty itself; iTerm2 is also supported through its inline image protocol. Other terminals still get safe text placeholders or local open image links when available. See the full OSC 8 adoption list for link support.
• For source builds only: Go 1.25 or newer and a C compiler such as clang or gcc for SQLite CGO support.

First launch shows setup wizard

herald

Homebrew is the default macOS install path. The formula installs `herald`,
whose `mcp` and `ssh` subcommands are the primary MCP and SSH entrypoints. It
also installs the compatibility wrappers `herald-mcp-server` and
`herald-ssh-server` for existing MCP configs and scripts. Release binaries
include the bundled Gmail OAuth defaults used when experimental OAuth
onboarding is explicitly enabled.

Update Homebrew metadata and upgrade Herald:

For a full Homebrew reset:

Direct browser downloads from GitHub are not Developer ID signed or notarized yet, so macOS Gatekeeper may warn until the packaging milestone adds signing.

Install from source with Go

```bash

Install the primary CLI from source (Go 1.25+ required)

go install github.com/herald-email/herald-mail-app/cmd/herald@latest

Or build from a checkout

git clone https://github.com/herald-email/herald-mail-app.git cd herald-mail-app make build

Run (first launch shows setup wizard)

./bin/herald

The canonical Go install path is `github.com/herald-email/herald-mail-app/cmd/herald`;
it installs a binary named `herald`. Use `herald mcp` and `herald ssh` for the
MCP and SSH surfaces. The legacy wrapper packages remain installable only for
existing configs and scripts that still call the old binary names:

---

Gmail Setup

Gmail IMAP with an App Password is the normal Gmail setup path while Gmail OAuth onboarding is experimental. The first-run wizard prefills imap.gmail.com:993 and smtp.gmail.com:587 for that path.

To configure Gmail over IMAP, turn on Google 2-Step Verification, create an App Password for Herald, then choose Gmail (IMAP + App Password) in the setup wizard.

Experimental OAuth onboarding is hidden from the first-run wizard unless Herald is launched with -experimental:

herald -experimental

If you choose Gmail OAuth (Experimental), Herald opens a browser authorization prompt and stores the resulting refresh token in your config so it can refresh access later. OAuth remains gated because Google OAuth onboarding and verification can take weeks and significant cost.

Helpful references:

• Google Workspace Help: Set up Gmail with a third-party email client
• Gmail Help: Add Gmail to another email client
• Gmail Help: Sign in with app passwords

Homebrew and release binaries include the desktop OAuth defaults used by the experimental Gmail OAuth wizard. Source builds do not embed those defaults unless you opt in.

For a one-off local run, export the credentials before launching Herald:

export HERALD_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export HERALD_GOOGLE_CLIENT_SECRET="your-client-secret"

For a local binary with OAuth defaults built in, copy .herald-release.env.example to .herald-release.env, fill it in, and run make build-release-local. Plain make build intentionally does not embed .herald-release.env; it creates a normal development binary.

---

MCP Setup

Herald exposes an MCP server over stdio through herald mcp, so AI tools can read and manage email without opening the TUI. The legacy herald-mcp-server binary remains available as a compatibility wrapper for older MCP configs.

```bash go install github.com/herald-email/herald-mail-app/cmd/herald@latest

Or build from a checkout:

go build -o bin/herald ./cmd/herald ```

Use ./bin/herald instead of herald in the examples below when you are testing the checkout binary directly.

Quick Start

Try The Demo First

Curious, but not ready to connect your inbox? Run Herald with a fictional mailbox, seeded contacts, attachments, threads, and deterministic demo AI:

```bash herald --demo

Configuration

Config file: ~/.herald/conf.yaml

credentials:
    username: "your@email.com"
    password: "your-password-or-app-password"
server:
    host: "imap.fastmail.com"
    port: 993
smtp:
    host: "smtp.fastmail.com"
    port: 587
ollama:
    host: "http://localhost:11434"
    model: "gemma3:4b" # for classification, chat, quick replies
    embedding_model: "nomic-embed-text-v2-moe" # for semantic search

Known server presets (auto-fill IMAP/SMTP): gmail, protonmail, fastmail, icloud, outlook

---