How MenuBar for HEY works with the HEY CLI

MenuBar for HEY ships the official hey command line tool inside the app and runs it as a child process on your Mac. Every piece of mail the app shows, and every change you make from the menu bar, goes through that tool. The app itself never talks to app.hey.com.

MenuBar for HEY is made by Soules Studio LTD. It is unofficial and not affiliated with 37signals, and HEY is a trademark of 37signals.

Last updated 28 September 2026.

The bundled CLI

The hey tool is made by 37signals and published as basecamp/hey-cli (opens in a new tab). MenuBar for HEY carries a pinned copy of it inside the app, and that copy is the only command line tool the app runs. There is nothing else to install.

Pinned means the version is chosen for each release of the app and tested with it before that release ships. The app never picks up a newer hey on its own. When the tool changes, an update to the app brings the new copy with it.

Pinning is what lets the app know exactly what the tool will answer: the shape of its JSON, the codes it exits with and the changes hey watch reports. A copy that changed underneath the app could break it on a day nobody chose. A pinned one changes only in a release that was tested with it.

To see which version your copy carries, open Settings, About. The app lists it there as HEY CLI, with its version number.

How sign in works

When you sign in, the app asks the bundled tool to do it. The tool opens HEY's sign in page in your browser, and you sign in there, on hey.com. The app never sees your password.

Once you are in, the tool keeps your sign in in the macOS Keychain and in its own config folder, ~/.config/hey-cli. Both are managed by the tool. The app never reads them, and it never stores a token of its own.

Already signed in with Homebrew

If you installed hey yourself with Homebrew and signed in with it, you do not need to sign in again. The bundled copy and your Homebrew copy share one sign in, because both keep it in the same Keychain entry and the same config folder. When MenuBar for HEY starts, you are already signed in.

The two copies run side by side without getting in each other's way. Because it is one sign in, it works the other way round too: signing out in the app signs your Homebrew copy out as well.

Live updates with hey watch

hey watch is a command that keeps running and prints one line of JSON for each change in your mail. MenuBar for HEY keeps one running for your Imbox, and that is how new threads reach the menu bar as they arrive rather than on a timer.

The alternative is polling, which means asking HEY again and again whether anything changed. With hey watch the app hears about a change in your Imbox when it happens, instead of asking on a schedule.

If the stream stops, the app starts it again, waiting a little longer after each failed try. It never falls back to polling your Imbox.

The Screener works differently. The app checks it for first time senders once a minute, so a new sender can take up to a minute to appear.

When you are signed out

The tool tells the app you are signed out with a dedicated exit code, whichever command it was running. When that happens, the app shows its sign in state, offers to sign you in, and shows no mail.

Signing back in is the same browser flow as the first time. Signing out from the app ends the same shared sign in, and deletes the copy of your last Imbox and Screener page the app keeps on your Mac.

What the app never does

• It never calls app.hey.com itself. Open in HEY hands the thread's address to your browser, which opens it like any other link.
• It never reads the Keychain entry or the config folder where the tool keeps your sign in.
• It never stores a token.
• It never retries a change that failed. If moving a thread or screening a sender does not go through, the app tells you, and you decide whether to try again.
• It reads the tool's answers as JSON only, never its text for people. How the tool words things on screen can change without confusing the app.

For what the app keeps on your Mac and what it sends, read how MenuBar for HEY handles your data.

HEYCliKit

The Swift package MenuBar for HEY uses to talk to the HEY CLI, HEYCliKit (opens in a new tab), is open source and MIT licensed.

HEYCliKit is the part that starts the tool, asks it for JSON and reads the answer. If you want to see exactly how the app talks to the tool, that is where to look. The app itself is a separate project, and its code is not published.

To see what the app does and to download it, go to MenuBar for HEY.