HEY CLI
A terminal CLI and TUI for HEY mail, calendar and contacts, used by a person or by an agent
- 415 ★ on the repository
- Last commit
Broad access
Why this level
- The agent reads the mail, contacts and calendar of your HEY account
- The agent saves drafts in your name, and it can run `hey draft send`, which sends a draft, through the terminal
Install
- Works in
Manual install
mise use -g github:basecamp/hey-cliA route without a script. Homebrew, Scoop, Nix and a source build are also available.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads the mail, contacts and calendar of your HEY account
- The agent saves drafts in your name, and it can run `hey draft send`, which sends a draft, through the terminal
This is third-party code. Review the repository files before installing.
What it does
HEY CLI is a terminal client for 37signals' HEY service. The hey command opens an app with mail, contacts, calendar and journal, and its subcommands do the same from scripts: they list boxes, read threads as Markdown, search mail, reply and create calendar events. When output goes to a pipe, commands return JSON, and the --jq flag filters it without a separate jq tool. The hey watch command prints one JSON line for every new email, so a handler is easy to attach. Agents get three routes: a built-in skill for Claude Code and Codex, the hey@37signals plugin for Claude Code, and the hey mcp server. The server saves mail only as drafts, and a person confirms sending.
Who it is for. For HEY users who read mail and plan meetings from the terminal or hand that work to Claude Code and Codex.
Good fit when
- You need to clear the inbox: open the imbox box, read a whole thread and prepare a reply
- You want a feed of new mail in a script: hey watch emits one JSON line per email
- An agent has to find mail from one sender over the last 30 days and summarise the correspondence
- You want to create a calendar event with one command, such as a meeting at 14:00 on a given day
- You need an MCP with reduced rights: a read-only mode or a set of domains such as boxes and search
Not a fit when
- You have no HEY account: the client works only with that service and does not connect to Gmail or other mail
- An agent has to send mail by itself through MCP: the server saves drafts only and refuses requests to send
- You need an unattended install on a server with no user: a person confirms the first sign-in in a browser
Example request
Show me emails from Ivan in the Imbox over the last week and draft a reply saying I can meet on Friday.Limitations
The client works only with the HEY service and needs an account. The first sign-in happens in a browser, and the session is then kept in the system keychain.
The script installer runs code downloaded from hey.com, so read it before running it. Options without a script exist: mise, Homebrew, Scoop, Nix and a source build.
An installed skill refreshes itself the first time a new release runs. Whether HEY is reachable from Russia was not checked for this card.
How to disable. The `hey setup agents --remove` command removes the skills and the Claude Code plugin that the CLI installed. Remove the MCP server with `claude mcp remove hey`, and uninstall the client the way you installed it.
FAQ
How do I connect HEY to Claude Code?
Run `hey`: the sign-in wizard finds installed agents and connects them. By hand, `hey setup claude` installs the skill and the hey@37signals plugin, and `claude mcp add hey -- hey mcp` adds MCP tools for your account.
Can an agent send mail through hey mcp?
No. Actions that create or change a message always save a draft, and requests to send, schedule or triage the thread in the same call are refused. A person sends the draft from HEY or with `hey draft send` and the draft number.
How do I keep the agent read-only?
Start the server as `hey mcp --read-only`. The `--domains` flag narrows the tool set, for example `--domains boxes,search` leaves only boxes and search.
How do I check that the install and sign-in are fine?
The `hey doctor` command checks the install, sign-in and the skill and plugin state for every detected agent.
Will hey overwrite my own skill with the same name?
No. The CLI writes only to skill directories it created itself and marks them with a `.managed-by-hey-cli` file. A hey directory without that marker is left untouched, and `hey doctor` explains how to adopt it.
Discussion
No questions or reviews yet.
Related
CLI toolsJob search inside your coding agent: scores each listing against your CV from 1 to 5, tailors a PDF resume, drafts letters and tracks applications
A Claude Code workflow where the agent searches job postings, scores fit against your profile, drafts a CV and cover letter, and helps prepare for interviews
A skill that makes the agent open with the action, number the steps and skip tangents
Obsidian skills
Obsidian Skills
Skills for agents working with Obsidian: Markdown with wikilinks, Bases, JSON Canvas, Obsidian CLI, Defuddle and Knap
A self-hosted knowledge base with block-level references and a built-in MCP server for connecting AI agents to your notes
The official Reactive Resume MCP server and skill: the agent builds and edits resumes and runs a job application tracker
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| HEY CLI (this entry) | yes | 415 | ||
| gws | no | 31,818 | a CLI for Google Workspace APIs including Gmail and Calendar, while hey works only with the HEY service | |
| email-mcp: an MCP server for IMAP and SMTP mail | no | key is optional | 135 | an MCP for several mail accounts over IMAP, while hey is a terminal client for one service |
README in short
Install options are mise, Omarchy, a script for macOS, Linux and WSL2, or PowerShell for Windows. The rest covers the first run, example commands for boxes, threads, search and calendar, and a section on agents. Every command has built-in help through --help.