hey-cli is a Go-based command-line and terminal UI tool from Basecamp that brings HEY email, contacts, calendars, todos, habits, time tracking, and journal entries into the terminal. It supports both interactive TUI browsing and scriptable CLI commands, offers structured JSON output with stable exit codes, and includes a built-in agent skill so coding agents like Claude Code or Codex can search, read, draft, and organize email through documented commands. The walkthrough covers installation on macOS via curl or Homebrew, OAuth login, working with threads, drafts, bulk replies, The Screener, linked accounts, live watch events, local config trust, shell completions, upgrading, and removal, plus the author's own recommendations on how to safely combine it with AI agents.
Table of contents
What is hey-cli?How hey-cli is builtWhat you needInstall hey-cli on macOSInstall with HomebrewSign in to HEYOpen the terminal interfaceFind the available commandsWork with email from the command lineOrganize your emailManage The ScreenerManage contactsWork with linked HEY accountsUse structured outputWatch for live changesManage calendars and personal dataConnect hey-cli to a coding agentConfiguration and local trustInstall shell completionsUpgrade hey-cliRemove hey-cliHow I would use hey-cliWhere hey-cli is not a good fitQuestions this post answers
How do I install hey-cli on macOS?
Run the official installer command curl -fsSL https://hey.com/install-cli | bash, which detects macOS and CPU architecture (Apple silicon or Intel), downloads the matching archive, verifies its SHA-256 checksum and Sigstore signature, extracts the hey executable, and adds it to PATH. Alternatively, install via Homebrew with brew install --cask basecamp/tap/hey, though upgrades then delegate to Homebrew instead of the built-in hey upgrade command. daily.dev surfaces install and setup guides like this for developers picking up new CLI tools.
What is the difference between the posting id and topic_id in hey-cli?
The posting id identifies an item inside a specific mailbox and is used for organization actions like moving, labeling, or marking a thread as seen, while topic_id identifies the email conversation itself and is used to read, reply, forward, or share a thread. Both IDs appear together in JSON output, and choosing the wrong one is a common mistake when scripting against hey-cli. Developers scripting against a new CLI's data model can find these nuances covered on daily.dev.
How can a coding agent like Claude Code or Codex access email through hey-cli?
hey-cli ships an embedded agent skill that teaches agents to use its documented command interface, choose correct IDs, and request structured JSON output. Running hey setup codex or hey setup claude connects the respective agent, or hey skill install adds just the shared skill; hey doctor checks integration health, and hey-cli only manages skill directories carrying its own .managed-by-hey-cli marker. daily.dev helps developers track how CLI tools like this expose agent-ready skills for coding assistants.