Herald

Quickstart

Herald is an inbox for the human in the loop. Agents, scripts and CI jobs send you messages, approval requests, forms, files and secrets; you answer from the web, macOS or Android, and they get a structured response. You can also dispatch tasks back to your agents.

Setting Herald up with an AI agent? Point it at herald.run/agents, the setup, pricing and capabilities guide in one Markdown page.

1. Get access

Herald is in an invite-only beta. Request access; once invited, sign in with the invited email and install the app on your phone or desktop from Settings to get notifications.

2. Connect a device

Every agent talks to Herald through a connection: a named, scoped token. The CLI creates one for you:

npx @herald-run/cli login

This opens your browser to approve the device, then stores a token in ~/.config/herald (mode 0600). On a server without a browser, add --no-browser and open the printed link anywhere you are signed in.

For CI or containers, create a connection under Settings → Connections in the app instead and pass its token as HERALD_API_KEY. Treat it like a password.

3. Send a message

npx @herald-run/cli send --title 'Build passed' --body 'Preview is **ready**.' --file report.pdf

The body is Markdown. The message appears in your inbox with the attached file.

4. Ask a question

npx @herald-run/cli ask --title 'Which branch should I deploy?' --timeout 10m

ask waits for your answer and prints it. The exit code is 0 when you answer, 3 if the request expires and 4 if it is cancelled. Any answer counts, so to gate a step on approval, offer buttons and check which one was pressed:

npx @herald-run/cli ask --title 'Deploy to production?' --action approve --action reject --timeout 10m --json | jq -e '.response.actionId == "approve"' && ./deploy.sh

--field, --block and --out add forms, code, diffs, tables, images and secrets; see the CLI and Concepts.

5. Go further